summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/i2a_ASN1_STRING.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libcrypto/man/i2a_ASN1_STRING.3255
1 files changed, 0 insertions, 255 deletions
diff --git a/src/lib/libcrypto/man/i2a_ASN1_STRING.3 b/src/lib/libcrypto/man/i2a_ASN1_STRING.3
deleted file mode 100644
index 7d46474775..0000000000
--- a/src/lib/libcrypto/man/i2a_ASN1_STRING.3
+++ /dev/null
@@ -1,255 +0,0 @@
1.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.5 2024/12/27 15:30:17 schwarze Exp $
2.\"
3.\" Copyright (c) 2019, 2021 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 27 2024 $
18.Dt I2A_ASN1_STRING 3
19.Os
20.Sh NAME
21.Nm i2a_ASN1_STRING ,
22.Nm i2a_ASN1_INTEGER ,
23.Nm i2a_ASN1_ENUMERATED ,
24.Nm a2i_ASN1_STRING ,
25.Nm a2i_ASN1_INTEGER ,
26.Nm a2i_ASN1_ENUMERATED
27.Nd hexadecimal dump of an ASN.1 string
28.Sh SYNOPSIS
29.In openssl/asn1.h
30.Ft int
31.Fo i2a_ASN1_STRING
32.Fa "BIO *out_bio"
33.Fa "const ASN1_STRING *a"
34.Fa "int type"
35.Fc
36.Ft int
37.Fo i2a_ASN1_INTEGER
38.Fa "BIO *out_bio"
39.Fa "const ASN1_INTEGER *a"
40.Fc
41.Ft int
42.Fo i2a_ASN1_ENUMERATED
43.Fa "BIO *out_bio"
44.Fa "const i2a_ASN1_ENUMERATED *a"
45.Fc
46.Ft int
47.Fo a2i_ASN1_STRING
48.Fa "BIO *in_bio"
49.Fa "ASN1_STRING *out_string"
50.Fa "char *buffer"
51.Fa "int size"
52.Fc
53.Ft int
54.Fo a2i_ASN1_INTEGER
55.Fa "BIO *in_bio"
56.Fa "ASN1_INTEGER *out_string"
57.Fa "char *buffer"
58.Fa "int size"
59.Fc
60.Ft int
61.Fo a2i_ASN1_ENUMERATED
62.Fa "BIO *in_bio"
63.Fa "ASN1_ENUMERATED *out_string"
64.Fa "char *buffer"
65.Fa "int size"
66.Fc
67.Sh DESCRIPTION
68The functions
69.Fn i2a_ASN1_STRING ,
70.Fn i2a_ASN1_INTEGER ,
71and
72.Fn i2a_ASN1_ENUMERATED
73write a hexadecimal representation of
74.Fa a
75to
76.Fa out_bio .
77The
78.Fa type
79argument is ignored.
80.Pp
81Each byte of
82.Xr ASN1_STRING_get0_data 3
83is written as a number consisting of two upper-case hexadecimal digits.
84After each group of 70 digits, a backslash and a linefeed
85are inserted before the next digit.
86.Pp
87If the
88.Xr ASN1_STRING_length 3
89of
90.Fa a
91is 0, instead a pair of zero digits
92.Pq Qq 00
93is written by
94.Fn i2a_ASN1_INTEGER
95and
96.Fn i2a_ASN1_ENUMERATED
97and a single zero digit
98.Pq Qq 0
99by
100.Fn i2a_ASN1_STRING .
101If
102.Fa a
103is a
104.Dv NULL
105pointer, nothing is written.
106.Pp
107If
108.Fa a
109represents a negative integer,
110.Fn i2a_ASN1_INTEGER
111prepends a minus sign to the output.
112.Pp
113The functions
114.Fn a2i_ASN1_STRING ,
115.Fn a2i_ASN1_INTEGER ,
116and
117.Fn a2i_ASN1_ENUMERATED
118parse a hexadecimal representation of an ASN.1 string into
119.Fa out_string .
120Both lower-case and upper-case hexadecimal digits are accepted.
121Every pair of input digits is converted into one output byte.
122.Pp
123On every input line, the trailing newline character and an optional
124carriage return character preceding it are ignored.
125The trailing newline need not be present on the last line.
126If there is a backslash character before the newline character,
127parsing is continued on the next input line.
128.Pp
129At least one pair of input digits is required by
130.Fn a2i_ASN1_INTEGER
131and
132.Fn a2i_ASN1_ENUMERATED ,
133whereas
134.Fn a2i_ASN1_STRING
135converts empty input to an empty string.
136.Pp
137These functions are able to parse the output of
138.Fn i2a_ASN1_ENUMERATED .
139They can parse the output of
140.Fn i2a_ASN1_INTEGER
141unless
142.Fa a
143was negative, and they can parse the output of
144.Fn i2a_ASN1_STRING
145unless the
146.Xr ASN1_STRING_length 3
147of
148.Fa a
149was 0.
150.Pp
151Parsing fails if an input line contains an odd number of input
152digits or if memory allocation fails.
153.Pp
154These functions use the
155.Fa buffer
156provided by the caller and assume it is at least
157.Fa size
158bytes long.
159It is unspecified what the buffer contains after the functions return.
160.Sh RETURN VALUES
161The functions
162.Fn i2a_ASN1_STRING ,
163.Fn i2a_ASN1_INTEGER ,
164and
165.Fn i2a_ASN1_ENUMERATED
166return the number of bytes written or \-1 if
167.Xr BIO_write 3
168fails.
169In particular, they all return 0 when
170.Fa a
171is a
172.Dv NULL
173pointer.
174.Fn i2a_ASN1_STRING
175returns 1 for an empty string or an even number greater than 1
176for a string that is not empty.
177.Fn i2a_ASN1_INTEGER
178returns an even number greater than 1 for positive input
179or an odd number greater than 2 for negative input.
180.Fn i2a_ASN1_ENUMERATED
181always returns a non-negative even number when successful.
182.Pp
183The functions
184.Fn a2i_ASN1_STRING ,
185.Fn a2i_ASN1_INTEGER ,
186and
187.Fn a2i_ASN1_ENUMERATED
188are intended to return 1 for success or 0 for failure, but see the
189.Sx BUGS
190section for a number of traps.
191.Sh SEE ALSO
192.Xr a2i_ipadd 3 ,
193.Xr ASN1_STRING_length 3 ,
194.Xr ASN1_STRING_new 3 ,
195.Xr ASN1_STRING_print_ex 3 ,
196.Xr i2a_ASN1_OBJECT 3 ,
197.Xr i2s_ASN1_INTEGER 3
198.Sh HISTORY
199.Fn i2a_ASN1_INTEGER
200and
201.Fn a2i_ASN1_INTEGER
202first appeared in SSLeay 0.6.0.
203.Fn i2a_ASN1_STRING
204and
205.Fn a2i_ASN1_STRING
206first appeared in SSLeay 0.6.5.
207.Fn a2i_ASN1_STRING
208has been part of the public API since SSLeay 0.6.5 and
209.Fn i2a_ASN1_STRING
210since SSLeay 0.8.0.
211These functions have been available since
212.Ox 2.4 .
213.Pp
214.Fn i2a_ASN1_ENUMERATED
215and
216.Fn a2i_ASN1_ENUMERATED
217first appeared in OpenSSL 0.9.2 and have been available since
218.Ox 2.6 .
219.Sh BUGS
220If the first call to
221.Xr BIO_gets 3
222does not return any data, even if that is caused by a fatal I/O error,
223if the BIO type does not support the
224.Dq gets
225operation, or if it is caused by the BIO being non-blocking,
226.Fn a2i_ASN1_STRING
227immediately succeeds and returns an empty
228.Fa out_string .
229.Pp
230If
231.Fn BIO_gets 3
232returns a partial line, for example because the given
233.Fa size
234is insufficient to contain one of the input lines
235or for reasons specific to the BIO type,
236.Fn a2i_ASN1_STRING ,
237.Fn a2i_ASN1_INTEGER ,
238and
239.Fn a2i_ASN1_ENUMERATED
240may fail or silently return a truncated result.
241The caller is responsible for providing a
242.Fa buffer
243of sufficient size to contain the longest possible input line
244and for choosing a BIO of a type that only returns complete
245input lines and does not perform partial reads.
246.Pp
247The functions
248.Fn a2i_ASN1_STRING ,
249.Fn a2i_ASN1_INTEGER ,
250and
251.Fn a2i_ASN1_ENUMERATED
252do not support non-blocking BIOs.
253Reading is terminated as soon as
254.Xr BIO_gets 3
255returns a value less than 1.