summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorschwarze <>2017-01-05 06:08:31 +0000
committerschwarze <>2017-01-05 06:08:31 +0000
commitefdbb5cc8b3a48ae12b0591437db388fb8837f5e (patch)
tree1248e891e91ca14543ce1aa465b0c2afebfb7d7e /src
parent6c1f3cb96dcae0fb7701e86ff054f69dac0f3ae6 (diff)
downloadopenbsd-efdbb5cc8b3a48ae12b0591437db388fb8837f5e.tar.gz
openbsd-efdbb5cc8b3a48ae12b0591437db388fb8837f5e.tar.bz2
openbsd-efdbb5cc8b3a48ae12b0591437db388fb8837f5e.zip
Complete rewrite, documenting 16 additional constructor/destructor pairs.
While OpenSSL does not document them, they are public in <openssl/asn1.h>, and OpenSSL does document the related decoders and encoders. It makes no sense to me to document object methods without documenting the public constructors as well. While here: Bugfix: The type assigned by ASN1_STRING_new() was wrong. Remove implementation details. Add small amounts of useful auxiliary information.
Diffstat (limited to 'src')
-rw-r--r--src/lib/libcrypto/man/ASN1_STRING_new.3287
1 files changed, 189 insertions, 98 deletions
diff --git a/src/lib/libcrypto/man/ASN1_STRING_new.3 b/src/lib/libcrypto/man/ASN1_STRING_new.3
index 75c5049a14..bd5f912b29 100644
--- a/src/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/src/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,136 +1,227 @@
1.\" $OpenBSD: ASN1_STRING_new.3,v 1.6 2016/12/12 12:52:12 schwarze Exp $ 1.\" $OpenBSD: ASN1_STRING_new.3,v 1.7 2017/01/05 06:08:31 schwarze Exp $
2.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400 2.\" OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
3.\" 3.\"
4.\" This file was written by Dr. Stephen Henson. 4.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
5.\" Copyright (c) 2002, 2006, 2015 The OpenSSL Project. All rights reserved.
6.\" 5.\"
7.\" Redistribution and use in source and binary forms, with or without 6.\" Permission to use, copy, modify, and distribute this software for any
8.\" modification, are permitted provided that the following conditions 7.\" purpose with or without fee is hereby granted, provided that the above
9.\" are met: 8.\" copyright notice and this permission notice appear in all copies.
10.\" 9.\"
11.\" 1. Redistributions of source code must retain the above copyright 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12.\" notice, this list of conditions and the following disclaimer. 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
13.\" 17.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright 18.Dd $Mdocdate: January 5 2017 $
15.\" notice, this list of conditions and the following disclaimer in
16.\" the documentation and/or other materials provided with the
17.\" distribution.
18.\"
19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgment:
21.\" "This product includes software developed by the OpenSSL Project
22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23.\"
24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25.\" endorse or promote products derived from this software without
26.\" prior written permission. For written permission, please contact
27.\" openssl-core@openssl.org.
28.\"
29.\" 5. Products derived from this software may not be called "OpenSSL"
30.\" nor may "OpenSSL" appear in their names without prior written
31.\" permission of the OpenSSL Project.
32.\"
33.\" 6. Redistributions of any form whatsoever must retain the following
34.\" acknowledgment:
35.\" "This product includes software developed by the OpenSSL Project
36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37.\"
38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\"
51.Dd $Mdocdate: December 12 2016 $
52.Dt ASN1_STRING_NEW 3 19.Dt ASN1_STRING_NEW 3
53.Os 20.Os
54.Sh NAME 21.Sh NAME
55.Nm ASN1_STRING_new , 22.Nm ASN1_STRING_new ,
56.Nm ASN1_STRING_type_new , 23.Nm ASN1_STRING_type_new ,
57.Nm ASN1_STRING_free 24.Nm ASN1_STRING_free
25.Nm ASN1_OCTET_STRING_new ,
26.Nm ASN1_OCTET_STRING_free ,
27.Nm ASN1_BIT_STRING_new ,
28.Nm ASN1_BIT_STRING_free ,
29.Nm ASN1_INTEGER_new ,
30.Nm ASN1_INTEGER_free ,
31.Nm ASN1_ENUMERATED_new ,
32.Nm ASN1_ENUMERATED_free ,
33.Nm ASN1_UTF8STRING_new ,
34.Nm ASN1_UTF8STRING_free ,
35.Nm ASN1_IA5STRING_new ,
36.Nm ASN1_IA5STRING_free ,
37.Nm ASN1_UNIVERSALSTRING_new ,
38.Nm ASN1_UNIVERSALSTRING_free ,
39.Nm ASN1_BMPSTRING_new ,
40.Nm ASN1_BMPSTRING_free ,
41.Nm ASN1_GENERALSTRING_new ,
42.Nm ASN1_GENERALSTRING_free ,
43.Nm ASN1_T61STRING_new ,
44.Nm ASN1_T61STRING_free ,
45.Nm ASN1_VISIBLESTRING_new ,
46.Nm ASN1_VISIBLESTRING_free ,
47.Nm ASN1_PRINTABLESTRING_new ,
48.Nm ASN1_PRINTABLESTRING_free ,
49.Nm ASN1_PRINTABLE_new ,
50.Nm ASN1_PRINTABLE_free ,
58.Nm DIRECTORYSTRING_new , 51.Nm DIRECTORYSTRING_new ,
59.Nm DIRECTORYSTRING_free , 52.Nm DIRECTORYSTRING_free ,
60.Nm DISPLAYTEXT_new , 53.Nm DISPLAYTEXT_new ,
61.Nm DISPLAYTEXT_free 54.Nm DISPLAYTEXT_free ,
62.Nd ASN1_STRING allocation functions 55.Nm ASN1_GENERALIZEDTIME_new ,
56.Nm ASN1_GENERALIZEDTIME_free ,
57.Nm ASN1_UTCTIME_new ,
58.Nm ASN1_UTCTIME_free ,
59.Nm ASN1_TIME_new ,
60.Nm ASN1_TIME_free ,
61.Nd allocate and free ASN1_STRING objects
63.Sh SYNOPSIS 62.Sh SYNOPSIS
64.In openssl/asn1.h 63.In openssl/asn1.h
65.Ft ASN1_STRING * 64.Ft ASN1_STRING *
66.Fo ASN1_STRING_new 65.Fn ASN1_STRING_new void
67.Fa void 66.Ft ASN1_STRING *
68.Fc 67.Fn ASN1_STRING_type_new "int type"
68.Ft void
69.Fn ASN1_STRING_free "ASN1_STRING *a"
70.Ft ASN1_OCTET_STRING *
71.Fn ASN1_OCTET_STRING_new void
72.Ft void
73.Fn ASN1_OCTET_STRING_free "ASN1_OCTET_STRING *a"
74.Ft ASN1_BIT_STRING *
75.Fn ASN1_BIT_STRING_new void
76.Ft void
77.Fn ASN1_BIT_STRING_free "ASN1_BIT_STRING *a"
78.Ft ASN1_INTEGER *
79.Fn ASN1_INTEGER_new void
80.Ft void
81.Fn ASN1_INTEGER_free "ASN1_INTEGER *a"
82.Ft ASN1_ENUMERATED *
83.Fn ASN1_ENUMERATED_new void
84.Ft void
85.Fn ASN1_ENUMERATED_free "ASN1_ENUMERATED *a"
86.Ft ASN1_UTF8STRING *
87.Fn ASN1_UTF8STRING_new void
88.Ft void
89.Fn ASN1_UTF8STRING_free "ASN1_UTF8STRING *a"
90.Ft ASN1_IA5STRING *
91.Fn ASN1_IA5STRING_new void
92.Ft void
93.Fn ASN1_IA5STRING_free "ASN1_IA5STRING *a"
94.Ft ASN1_UNIVERSALSTRING *
95.Fn ASN1_UNIVERSALSTRING_new void
96.Ft void
97.Fn ASN1_UNIVERSALSTRING_free "ASN1_UNIVERSALSTRING *a"
98.Ft ASN1_BMPSTRING *
99.Fn ASN1_BMPSTRING_new void
100.Ft void
101.Fn ASN1_BMPSTRING_free "ASN1_BMPSTRING *a"
102.Ft ASN1_GENERALSTRING *
103.Fn ASN1_GENERALSTRING_new void
104.Ft void
105.Fn ASN1_GENERALSTRING_free "ASN1_GENERALSTRING *a"
106.Ft ASN1_T61STRING *
107.Fn ASN1_T61STRING_new void
108.Ft void
109.Fn ASN1_T61STRING_free "ASN1_T61STRING *a"
110.Ft ASN1_VISIBLESTRING *
111.Fn ASN1_VISIBLESTRING_new void
112.Ft void
113.Fn ASN1_VISIBLESTRING_free "ASN1_VISIBLESTRING *a"
114.Ft ASN1_PRINTABLESTRING *
115.Fn ASN1_PRINTABLESTRING_new void
116.Ft void
117.Fn ASN1_PRINTABLESTRING_free "ASN1_PRINTABLESTRING *a"
69.Ft ASN1_STRING * 118.Ft ASN1_STRING *
70.Fo ASN1_STRING_type_new 119.Fn ASN1_PRINTABLE_new void
71.Fa "int type"
72.Fc
73.Ft void 120.Ft void
74.Fo ASN1_STRING_free 121.Fn ASN1_PRINTABLE_free "ASN1_STRING *a"
75.Fa "ASN1_STRING *a"
76.Fc
77.Ft ASN1_STRING * 122.Ft ASN1_STRING *
78.Fo DIRECTORYSTRING_new 123.Fn DIRECTORYSTRING_new void
79.Fa void
80.Fc
81.Ft void 124.Ft void
82.Fo DIRECTORYSTRING_free 125.Fn DIRECTORYSTRING_free "ASN1_STRING *a"
83.Fa "ASN1_STRING *a"
84.Fc
85.Ft ASN1_STRING * 126.Ft ASN1_STRING *
86.Fo DISPLAYTEXT_new 127.Fn DISPLAYTEXT_new void
87.Fa void 128.Ft void
88.Fc 129.Fn DISPLAYTEXT_free "ASN1_STRING *a"
130.Ft ASN1_GENERALIZEDTIME *
131.Fn ASN1_GENERALIZEDTIME_new void
132.Ft void
133.Fn ASN1_GENERALIZEDTIME_free "ASN1_GENERALIZEDTIME *a"
134.Ft ASN1_UTCTIME *
135.Fn ASN1_UTCTIME_new void
136.Ft void
137.Fn ASN1_UTCTIME_free "ASN1_UTCTIME *a"
138.Ft ASN1_TIME *
139.Fn ASN1_TIME_new void
89.Ft void 140.Ft void
90.Fo DISPLAYTEXT_free 141.Fn ASN1_TIME_free "ASN1_TIME *a"
91.Fa "ASN1_STRING *a"
92.Fc
93.Sh DESCRIPTION 142.Sh DESCRIPTION
94.Fn ASN1_STRING_new , 143The
95.Fn DIRECTORYSTRING_new ,
96and
97.Fn DISPLAYTEXT_new
98return an allocated
99.Vt ASN1_STRING 144.Vt ASN1_STRING
100structure. 145object can represent a variety of ASN.1 built-in types.
101Its type is undefined. 146It can store a type and a value.
102.Pp 147.Pp
103.Fn ASN1_STRING_type_new 148All the
104returns an allocated 149.Fn *_new
150functions
151allocate and initialize an empty
105.Vt ASN1_STRING 152.Vt ASN1_STRING
106structure of type 153object.
107.Fa type . 154The following table shows the type assigned to the new object,
155and which ASN.1 type it represents.
156.Bl -column "ASN1_GENERALIZEDTIME_new()" "V_ASN1_GENERALIZEDTIME"
157.It Em constructor function Ta Em OpenSSL type Ta Em ASN.1 type
158.It Ta
159.It Fn ASN1_STRING_new Ta Dv V_ASN1_OCTET_STRING
160.It Fn ASN1_STRING_type_new Ta Fa type No argument
161.It Ta
162.It Fn ASN1_OCTET_STRING_new Ta Dv V_ASN1_OCTET_STRING Ta OCTET STRING
163.It Fn ASN1_BIT_STRING_new Ta Dv V_ASN1_BIT_STRING Ta BIT STRING
164.It Fn ASN1_INTEGER_new Ta Dv V_ASN1_INTEGER Ta INTEGER
165.It Fn ASN1_ENUMERATED_new Ta Dv V_ASN1_ENUMERATED Ta ENUMERATED
166.It Ta
167.It Fn ASN1_UTF8STRING_new Ta Dv V_ASN1_UTF8STRING Ta UTF8String
168.It Fn ASN1_IA5STRING_new Ta Dv V_ASN1_IA5STRING Ta IA5String
169.It Ta
170.It Fn ASN1_UNIVERSALSTRING_new Ta Dv V_ASN1_UNIVERSALSTRING Ta UniversalString
171.It Fn ASN1_BMPSTRING_new Ta Dv V_ASN1_BMPSTRING Ta BMPString
172.It Fn ASN1_GENERALSTRING_new Ta Dv V_ASN1_GENERALSTRING Ta GeneralString
173.It Fn ASN1_T61STRING_new Ta Dv V_ASN1_T61STRING Ta T61String
174.It Fn ASN1_VISIBLESTRING_new Ta Dv V_ASN1_VISIBLESTRING Ta VisibleString
175.It Fn ASN1_PRINTABLESTRING_new Ta Dv V_ASN1_PRINTABLESTRING Ta PrintableString
176.It Ta
177.It Fn ASN1_PRINTABLE_new Ta Dv V_ASN1_UNDEF
178.It Fn DIRECTORYSTRING_new Ta Dv V_ASN1_UNDEF
179.It Fn DISPLAYTEXT_new Ta Dv V_ASN1_UNDEF
180.It Ta
181.It Fn ASN1_GENERALIZEDTIME_new Ta Dv V_ASN1_GENERALIZEDTIME Ta GeneralizedTime
182.It Fn ASN1_UTCTIME_new Ta Dv V_ASN1_UTCTIME Ta UTCTime
183.It Fn ASN1_TIME_new Ta Dv V_ASN1_UNDEF Ta TIME
184.El
108.Pp 185.Pp
109.Fn ASN1_STRING_free , 186All the
110.Fn DIRECTORYSTRING_free , 187.Fa *_free
111and 188functions free
112.Fn DISPLAYTEXT_free 189.Fa a
113free up 190including any data contained in it.
114.Fa a .
115If 191If
116.Fa a 192.Fa a
117is a 193is a
118.Dv NULL 194.Dv NULL
119pointer, no action occurs. 195pointer, no action occurs.
120.Pp
121Other string types call the ASN1_STRING functions.
122For example
123.Fn ASN1_OCTET_STRING_new
124calls
125.Fn ASN1_STRING_type V_ASN1_OCTET_STRING .
126.Sh RETURN VALUES 196.Sh RETURN VALUES
127.Fn ASN1_STRING_new 197All the
128and 198.Fa *_new
129.Fn ASN1_STRING_type_new 199functions return the new
130return a valid
131.Vt ASN1_STRING 200.Vt ASN1_STRING
132structure or 201object or
133.Dv NULL 202.Dv NULL
134if an error occurred. 203if an error occurs.
135.Sh SEE ALSO 204.Sh SEE ALSO
205.Xr ASN1_time_parse 3 ,
206.Xr ASN1_TIME_set 3 ,
136.Xr ERR_get_error 3 207.Xr ERR_get_error 3
208.Sh BUGS
209.Vt ASN1_OCTET_STRING ,
210.Vt ASN1_BIT_STRING ,
211.Vt ASN1_INTEGER ,
212.Vt ASN1_ENUMERATED ,
213.Vt ASN1_UTF8STRING ,
214.Vt ASN1_IA5STRING ,
215.Vt ASN1_UNIVERSALSTRING ,
216.Vt ASN1_BMPSTRING ,
217.Vt ASN1_GENERALSTRING ,
218.Vt ASN1_T61STRING ,
219.Vt ASN1_VISIBLESTRING ,
220.Vt ASN1_PRINTABLESTRING ,
221.Vt ASN1_GENERALIZEDTIME ,
222.Vt ASN1_UTCTIME ,
223and
224.Vt ASN1_TIME
225are merely typedef aliases of
226.Vt ASN1_STRING
227and provide no type safety whatsoever.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-21 15:03:20 +0000