doc/man3/X509_get_subject_name.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_NAME_hash_ex, X509_NAME_hash,
   6 X509_get_subject_name, X509_set_subject_name, X509_subject_name_hash,
   7 X509_get_issuer_name, X509_set_issuer_name, X509_issuer_name_hash,
   8 X509_REQ_get_subject_name, X509_REQ_set_subject_name,
   9 X509_ACERT_get0_issuerName, X509_ACERT_set1_issuerName,
  10 X509_CRL_get_issuer, X509_CRL_set_issuer_name -
  11 get X509_NAME hashes or get and set issuer or subject names
  12
  13 =head1 SYNOPSIS
  14
  15  #include <openssl/x509.h>
  16
  17  unsigned long X509_NAME_hash_ex(const X509_NAME *x, OSSL_LIB_CTX *libctx,
  18                                  const char *propq, int *ok);
  19
  20  X509_NAME *X509_get_subject_name(const X509 *x);
  21  int X509_set_subject_name(X509 *x, const X509_NAME *name);
  22  unsigned long X509_subject_name_hash(X509 *x);
  23
  24  X509_NAME *X509_get_issuer_name(const X509 *x);
  25  int X509_set_issuer_name(X509 *x, const X509_NAME *name);
  26  unsigned long X509_issuer_name_hash(X509 *x);
  27
  28  X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req);
  29  int X509_REQ_set_subject_name(X509_REQ *req, const X509_NAME *name);
  30
  31  X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl);
  32  int X509_CRL_set_issuer_name(X509_CRL *x, const X509_NAME *name);
  33
  34  #include <openssl/x509_acert.h>
  35
  36  X509_NAME *X509_ACERT_get0_issuerName(const X509_ACERT *x);
  37  int X509_ACERT_set1_issuerName(X509_ACERT *x, const X509_NAME *name);
  38
  39 The following macro has been deprecated since OpenSSL 3.0, and can be
  40 hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
  41 see L<openssl_user_macros(7)>:
  42
  43  #define X509_NAME_hash(x) X509_NAME_hash_ex(x, NULL, NULL, NULL)
  44
  45 =head1 DESCRIPTION
  46
  47 X509_NAME_hash_ex() returns a hash value of name I<x> or 0 on failure,
  48 using any given library context I<libctx> and property query I<propq>.
  49 The I<ok> result argument may be NULL
  50 or else is used to return 1 for success and 0 for failure.
  51 Failure may happen on malloc error or if no SHA1 implementation is available.
  52
  53 X509_NAME_hash() returns a hash value of name I<x> or 0 on failure,
  54 using the default library context and default property query.
  55
  56 X509_get_subject_name() returns the subject name of certificate I<x>. The
  57 returned value is an internal pointer which B<MUST NOT> be freed.
  58
  59 X509_set_subject_name() sets the issuer name of certificate I<x> to
  60 I<name>. The I<name> parameter is copied internally and should be freed
  61 up when it is no longer needed.
  62
  63 X509_subject_name_hash() returns a hash value of the subject name of
  64 certificate I<x>.
  65
  66 X509_get_issuer_name(), X509_set_issuer_name(), and X509_issuer_name_hash()
  67 are identical to
  68 X509_get_subject_name(), X509_set_subject_name(), and X509_subject_name_hash()
  69 except they relate to the issuer name of I<x>.
  70
  71 Similarly X509_REQ_get_subject_name(), X509_REQ_set_subject_name(),
  72 X509_ACERT_get0_issuerName(), X509_ACERT_set1_issuerName(),
  73 X509_CRL_get_issuer() and X509_CRL_set_issuer_name() get or set the subject
  74 or issuer names of certificate requests of CRLs respectively.
  75
  76 Since attribute certificates do not have a subject name, only the issuer name
  77 can be set.  For details on setting X509_ACERT holder identities, see
  78 L<X509_ACERT_set0_holder_entityName(3)>.
  79
  80 =head1 RETURN VALUES
  81
  82 X509_get_subject_name(), X509_get_issuer_name(), X509_REQ_get_subject_name()
  83 X509_ACERT_get0_issuerName() and X509_CRL_get_issuer() return
  84 an B<X509_NAME> pointer.
  85
  86 X509_NAME_hash_ex(), X509_NAME_hash(),
  87 X509_subject_name_hash() and X509_issuer_name_hash()
  88 return the first four bytes of the SHA1 hash value,
  89 converted to B<unsigned long> in little endian order,
  90 or 0 on failure.
  91
  92 X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name(),
  93 X509_ACERT_get0_issuerName() and X509_CRL_set_issuer_name() return 1 for
  94 success and 0 for failure.
  95
  96 =head1 BUGS
  97
  98 In case X509_NAME_hash(), X509_subject_name_hash(), or X509_issuer_name_hash()
  99 returns 0 it remains unclear if this is the real hash value or due to failure.
 100 Better use X509_NAME_hash_ex() instead.
 101
 102 =head1 SEE ALSO
 103
 104 L<d2i_X509(3)>,
 105 L<ERR_get_error(3)>, L<d2i_X509(3)>
 106 L<X509_CRL_get0_by_serial(3)>,
 107 L<X509_get0_signature(3)>,
 108 L<X509_get_ext_d2i(3)>,
 109 L<X509_get_extension_flags(3)>,
 110 L<X509_get_pubkey(3)>,
 111 L<X509_NAME_add_entry_by_txt(3)>,
 112 L<X509_NAME_ENTRY_get_object(3)>,
 113 L<X509_NAME_get_index_by_NID(3)>,
 114 L<X509_NAME_print_ex(3)>,
 115 L<X509_new(3)>,
 116 L<X509_sign(3)>,
 117 L<X509V3_get_d2i(3)>,
 118 L<X509_verify_cert(3)>
 119
 120 =head1 HISTORY
 121
 122 X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in
 123 earlier versions.
 124
 125 X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was previously
 126 added in OpenSSL 1.0.0 as a macro.
 127
 128 X509_NAME_hash() was turned into a macro and deprecated in OpenSSL 3.0.
 129
 130 =head1 COPYRIGHT
 131
 132 Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
 133
 134 Licensed under the Apache License 2.0 (the "License").  You may not use
 135 this file except in compliance with the License.  You can obtain a copy
 136 in the file LICENSE in the source distribution or at
 137 L<https://www.openssl.org/source/license.html>.
 138
 139 =cut