lib/libcrypto/man/GENERAL_NAME_new.3

   1 .\"     $OpenBSD: GENERAL_NAME_new.3,v 1.2 2016/12/25 22:15:10 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: December 25 2016 $
  18 .Dt GENERAL_NAME_NEW 3
  19 .Os
  20 .Sh NAME
  21 .Nm GENERAL_NAME_new ,
  22 .Nm GENERAL_NAME_free ,
  23 .Nm GENERAL_NAMES_new ,
  24 .Nm GENERAL_NAMES_free ,
  25 .Nm EDIPARTYNAME_new ,
  26 .Nm EDIPARTYNAME_free ,
  27 .Nm OTHERNAME_new ,
  28 .Nm OTHERNAME_free
  29 .Nd names for use in X.509 extensions
  30 .Sh SYNOPSIS
  31 .In openssl/x509v3.h
  32 .Ft GENERAL_NAME *
  33 .Fn GENERAL_NAME_new void
  34 .Ft void
  35 .Fn GENERAL_NAME_free "GENERAL_NAME *name"
  36 .Ft GENERAL_NAMES *
  37 .Fn GENERAL_NAMES_new void
  38 .Ft void
  39 .Fn GENERAL_NAMES_free "GENERAL_NAMES *names"
  40 .Ft EDIPARTYNAME *
  41 .Fn EDIPARTYNAME_new void
  42 .Ft void
  43 .Fn EDIPARTYNAME_free "EDIPARTYNAME *name"
  44 .Ft OTHERNAME *
  45 .Fn OTHERNAME_new void
  46 .Ft void
  47 .Fn OTHERNAME_free "OTHERNAME *name"
  48 .Sh DESCRIPTION
  49 Even though the X.501
  50 .Vt Name
  51 documented in
  52 .Xr X509_NAME_new 3
  53 is a complicated multi-layered structure, it is very rigid and not
  54 flexible enough to represent various entities that many people want
  55 to use as names in certificates.
  56 For that reason, X.509 extensions use the X.509
  57 .Vt GeneralName
  58 wrapper structure rather than using the X.501
  59 .Vt Name
  60 structure directly, at the expense of adding one or two additional
  61 layers of indirection.
  62 .Pp
  63 .Fn GENERAL_NAME_new
  64 allocates and initializes an empty
  65 .Vt GENERAL_NAME
  66 object, representing the ASN.1
  67 .Vt GeneralName
  68 structure defined in RFC 5280 section 4.2.1.6.
  69 It can for example hold an
  70 .Vt X509_name
  71 object, an IP address, a DNS host name, a uniform resource identifier,
  72 an email address, or an
  73 .Vt EDIPARTYNAME
  74 or
  75 .Vt OTHERNAME
  76 object described below.
  77 .Fn GENERAL_NAME_free
  78 frees
  79 .Fa name .
  80 .Pp
  81 .Fn GENERAL_NAMES_new
  82 allocates and initializes an empty
  83 .Vt GENERAL_NAMES
  84 object, which is a
  85 .Vt STACK_OF(GENERAL_NAME)
  86 and represents the ASN.1
  87 .Vt GeneralNames
  88 structure defined in RFC 5280 section 4.2.1.6.
  89 It is used by extension structures that can contain multiple names,
  90 for example key identifier, alternative name, and distribution point
  91 extensions.
  92 .Fn GENERAL_NAMES_free
  93 frees
  94 .Fa names .
  95 .Pp
  96 .Fn EDIPARTYNAME_new
  97 allocates and initializes an empty
  98 .Vt EDIPARTYNAME
  99 object, representing the ASN.1
 100 .Vt EDIPartyName
 101 structure defined in RFC 5280 section 4.2.1.6, where
 102 .Dq EDI
 103 stands for
 104 .Dq electronic data identifier .
 105 It can hold two strings, the name itself and the name of the authority
 106 that assigned that name.
 107 .Fn EDIPARTYNAME_free
 108 frees
 109 .Fa name .
 110 .Pp
 111 .Fn OTHERNAME_new
 112 allocates and initializes an empty
 113 .Vt OTHERNAME
 114 object, representing the ASN.1
 115 .Vt OtherName
 116 structure defined in RFC 5280 section 4.2.1.6.
 117 It can hold data of any
 118 .Vt ASN1_TYPE
 119 together with a type identifier.
 120 .Fn OTHERNAME_free
 121 frees
 122 .Fa name .
 123 .Sh RETURN VALUES
 124 .Fn GENERAL_NAME_new ,
 125 .Fn GENERAL_NAMES_new ,
 126 .Fn EDIPARTYNAME_new ,
 127 and
 128 .Fn OTHERNAME_new
 129 return a new
 130 .Vt GENERAL_NAME ,
 131 .Vt GENERAL_NAMES ,
 132 .Vt EDIPARTYNAME ,
 133 or
 134 .Vt OTHERNAME
 135 object or
 136 .Dv NULL
 137 if an error occurs.
 138 .Sh SEE ALSO
 139 .Xr X509_EXTENSION_new 3 ,
 140 .Xr X509_NAME_new 3
 141 .Sh STANDARDS
 142 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 143 Certificate Revocation List (CRL) Profile,
 144 section 4.2: Certificate Extensions