1.\"	$OpenBSD: GENERAL_NAME_new.3,v 1.6 2019/06/06 01:06:58 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: June 6 2019 $
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
49Even though the X.501
50.Vt Name
51documented in
52.Xr X509_NAME_new 3
53is a complicated multi-layered structure, it is very rigid and not
54flexible enough to represent various entities that many people want
55to use as names in certificates.
56For that reason, X.509 extensions use the X.509
57.Vt GeneralName
58wrapper structure rather than using the X.501
59.Vt Name
60structure directly, at the expense of adding one or two additional
61layers of indirection.
62.Pp
63.Fn GENERAL_NAME_new
64allocates and initializes an empty
65.Vt GENERAL_NAME
66object, representing the ASN.1
67.Vt GeneralName
68structure defined in RFC 5280 section 4.2.1.6.
69It can for example hold an
70.Vt X509_name
71object, an IP address, a DNS host name, a uniform resource identifier,
72an email address, or an
73.Vt EDIPARTYNAME
74or
75.Vt OTHERNAME
76object described below.
77.Fn GENERAL_NAME_free
78frees
79.Fa name .
80.Pp
81.Fn GENERAL_NAMES_new
82allocates and initializes an empty
83.Vt GENERAL_NAMES
84object, which is a
85.Vt STACK_OF(GENERAL_NAME)
86and represents the ASN.1
87.Vt GeneralNames
88structure defined in RFC 5280 section 4.2.1.6.
89It is used by extension structures that can contain multiple names,
90for example key identifier, alternative name, and distribution point
91extensions.
92.Fn GENERAL_NAMES_free
93frees
94.Fa names .
95.Pp
96.Fn EDIPARTYNAME_new
97allocates and initializes an empty
98.Vt EDIPARTYNAME
99object, representing the ASN.1
100.Vt EDIPartyName
101structure defined in RFC 5280 section 4.2.1.6, where
102.Dq EDI
103stands for
104.Dq electronic data identifier .
105It can hold two strings, the name itself and the name of the authority
106that assigned that name.
107.Fn EDIPARTYNAME_free
108frees
109.Fa name .
110.Pp
111.Fn OTHERNAME_new
112allocates and initializes an empty
113.Vt OTHERNAME
114object, representing the ASN.1
115.Vt OtherName
116structure defined in RFC 5280 section 4.2.1.6.
117It can hold data of any
118.Vt ASN1_TYPE
119together with a type identifier.
120.Fn OTHERNAME_free
121frees
122.Fa name .
123.Sh RETURN VALUES
124.Fn GENERAL_NAME_new ,
125.Fn GENERAL_NAMES_new ,
126.Fn EDIPARTYNAME_new ,
127and
128.Fn OTHERNAME_new
129return a new
130.Vt GENERAL_NAME ,
131.Vt GENERAL_NAMES ,
132.Vt EDIPARTYNAME ,
133or
134.Vt OTHERNAME
135object or
136.Dv NULL
137if an error occurs.
138.Sh SEE ALSO
139.Xr d2i_GENERAL_NAME 3 ,
140.Xr X509_EXTENSION_new 3 ,
141.Xr X509_NAME_new 3
142.Sh STANDARDS
143RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
144Certificate Revocation List (CRL) Profile,
145section 4.2: Certificate Extensions
146.Sh HISTORY
147.Fn GENERAL_NAME_new ,
148.Fn GENERAL_NAME_free ,
149.Fn GENERAL_NAMES_new ,
150and
151.Fn GENERAL_NAMES_free
152first appeared in OpenSSL 0.9.2b and have been available since
153.Ox 2.6 .
154.Pp
155.Fn OTHERNAME_new
156and
157.Fn OTHERNAME_free
158first appeared in OpenSSL 0.9.5 and have been available since
159.Ox 2.7 .
160.Pp
161.Fn EDIPARTYNAME_new
162and
163.Fn EDIPARTYNAME_free
164first appeared in OpenSSL 0.9.7 and have been available since
165.Ox 3.2 .
166