diff options
Diffstat (limited to 'src/lib/libcrypto/man/i2a_ASN1_STRING.3')
-rw-r--r-- | src/lib/libcrypto/man/i2a_ASN1_STRING.3 | 255 |
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 | ||
68 | The functions | ||
69 | .Fn i2a_ASN1_STRING , | ||
70 | .Fn i2a_ASN1_INTEGER , | ||
71 | and | ||
72 | .Fn i2a_ASN1_ENUMERATED | ||
73 | write a hexadecimal representation of | ||
74 | .Fa a | ||
75 | to | ||
76 | .Fa out_bio . | ||
77 | The | ||
78 | .Fa type | ||
79 | argument is ignored. | ||
80 | .Pp | ||
81 | Each byte of | ||
82 | .Xr ASN1_STRING_get0_data 3 | ||
83 | is written as a number consisting of two upper-case hexadecimal digits. | ||
84 | After each group of 70 digits, a backslash and a linefeed | ||
85 | are inserted before the next digit. | ||
86 | .Pp | ||
87 | If the | ||
88 | .Xr ASN1_STRING_length 3 | ||
89 | of | ||
90 | .Fa a | ||
91 | is 0, instead a pair of zero digits | ||
92 | .Pq Qq 00 | ||
93 | is written by | ||
94 | .Fn i2a_ASN1_INTEGER | ||
95 | and | ||
96 | .Fn i2a_ASN1_ENUMERATED | ||
97 | and a single zero digit | ||
98 | .Pq Qq 0 | ||
99 | by | ||
100 | .Fn i2a_ASN1_STRING . | ||
101 | If | ||
102 | .Fa a | ||
103 | is a | ||
104 | .Dv NULL | ||
105 | pointer, nothing is written. | ||
106 | .Pp | ||
107 | If | ||
108 | .Fa a | ||
109 | represents a negative integer, | ||
110 | .Fn i2a_ASN1_INTEGER | ||
111 | prepends a minus sign to the output. | ||
112 | .Pp | ||
113 | The functions | ||
114 | .Fn a2i_ASN1_STRING , | ||
115 | .Fn a2i_ASN1_INTEGER , | ||
116 | and | ||
117 | .Fn a2i_ASN1_ENUMERATED | ||
118 | parse a hexadecimal representation of an ASN.1 string into | ||
119 | .Fa out_string . | ||
120 | Both lower-case and upper-case hexadecimal digits are accepted. | ||
121 | Every pair of input digits is converted into one output byte. | ||
122 | .Pp | ||
123 | On every input line, the trailing newline character and an optional | ||
124 | carriage return character preceding it are ignored. | ||
125 | The trailing newline need not be present on the last line. | ||
126 | If there is a backslash character before the newline character, | ||
127 | parsing is continued on the next input line. | ||
128 | .Pp | ||
129 | At least one pair of input digits is required by | ||
130 | .Fn a2i_ASN1_INTEGER | ||
131 | and | ||
132 | .Fn a2i_ASN1_ENUMERATED , | ||
133 | whereas | ||
134 | .Fn a2i_ASN1_STRING | ||
135 | converts empty input to an empty string. | ||
136 | .Pp | ||
137 | These functions are able to parse the output of | ||
138 | .Fn i2a_ASN1_ENUMERATED . | ||
139 | They can parse the output of | ||
140 | .Fn i2a_ASN1_INTEGER | ||
141 | unless | ||
142 | .Fa a | ||
143 | was negative, and they can parse the output of | ||
144 | .Fn i2a_ASN1_STRING | ||
145 | unless the | ||
146 | .Xr ASN1_STRING_length 3 | ||
147 | of | ||
148 | .Fa a | ||
149 | was 0. | ||
150 | .Pp | ||
151 | Parsing fails if an input line contains an odd number of input | ||
152 | digits or if memory allocation fails. | ||
153 | .Pp | ||
154 | These functions use the | ||
155 | .Fa buffer | ||
156 | provided by the caller and assume it is at least | ||
157 | .Fa size | ||
158 | bytes long. | ||
159 | It is unspecified what the buffer contains after the functions return. | ||
160 | .Sh RETURN VALUES | ||
161 | The functions | ||
162 | .Fn i2a_ASN1_STRING , | ||
163 | .Fn i2a_ASN1_INTEGER , | ||
164 | and | ||
165 | .Fn i2a_ASN1_ENUMERATED | ||
166 | return the number of bytes written or \-1 if | ||
167 | .Xr BIO_write 3 | ||
168 | fails. | ||
169 | In particular, they all return 0 when | ||
170 | .Fa a | ||
171 | is a | ||
172 | .Dv NULL | ||
173 | pointer. | ||
174 | .Fn i2a_ASN1_STRING | ||
175 | returns 1 for an empty string or an even number greater than 1 | ||
176 | for a string that is not empty. | ||
177 | .Fn i2a_ASN1_INTEGER | ||
178 | returns an even number greater than 1 for positive input | ||
179 | or an odd number greater than 2 for negative input. | ||
180 | .Fn i2a_ASN1_ENUMERATED | ||
181 | always returns a non-negative even number when successful. | ||
182 | .Pp | ||
183 | The functions | ||
184 | .Fn a2i_ASN1_STRING , | ||
185 | .Fn a2i_ASN1_INTEGER , | ||
186 | and | ||
187 | .Fn a2i_ASN1_ENUMERATED | ||
188 | are intended to return 1 for success or 0 for failure, but see the | ||
189 | .Sx BUGS | ||
190 | section 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 | ||
200 | and | ||
201 | .Fn a2i_ASN1_INTEGER | ||
202 | first appeared in SSLeay 0.6.0. | ||
203 | .Fn i2a_ASN1_STRING | ||
204 | and | ||
205 | .Fn a2i_ASN1_STRING | ||
206 | first appeared in SSLeay 0.6.5. | ||
207 | .Fn a2i_ASN1_STRING | ||
208 | has been part of the public API since SSLeay 0.6.5 and | ||
209 | .Fn i2a_ASN1_STRING | ||
210 | since SSLeay 0.8.0. | ||
211 | These functions have been available since | ||
212 | .Ox 2.4 . | ||
213 | .Pp | ||
214 | .Fn i2a_ASN1_ENUMERATED | ||
215 | and | ||
216 | .Fn a2i_ASN1_ENUMERATED | ||
217 | first appeared in OpenSSL 0.9.2 and have been available since | ||
218 | .Ox 2.6 . | ||
219 | .Sh BUGS | ||
220 | If the first call to | ||
221 | .Xr BIO_gets 3 | ||
222 | does not return any data, even if that is caused by a fatal I/O error, | ||
223 | if the BIO type does not support the | ||
224 | .Dq gets | ||
225 | operation, or if it is caused by the BIO being non-blocking, | ||
226 | .Fn a2i_ASN1_STRING | ||
227 | immediately succeeds and returns an empty | ||
228 | .Fa out_string . | ||
229 | .Pp | ||
230 | If | ||
231 | .Fn BIO_gets 3 | ||
232 | returns a partial line, for example because the given | ||
233 | .Fa size | ||
234 | is insufficient to contain one of the input lines | ||
235 | or for reasons specific to the BIO type, | ||
236 | .Fn a2i_ASN1_STRING , | ||
237 | .Fn a2i_ASN1_INTEGER , | ||
238 | and | ||
239 | .Fn a2i_ASN1_ENUMERATED | ||
240 | may fail or silently return a truncated result. | ||
241 | The caller is responsible for providing a | ||
242 | .Fa buffer | ||
243 | of sufficient size to contain the longest possible input line | ||
244 | and for choosing a BIO of a type that only returns complete | ||
245 | input lines and does not perform partial reads. | ||
246 | .Pp | ||
247 | The functions | ||
248 | .Fn a2i_ASN1_STRING , | ||
249 | .Fn a2i_ASN1_INTEGER , | ||
250 | and | ||
251 | .Fn a2i_ASN1_ENUMERATED | ||
252 | do not support non-blocking BIOs. | ||
253 | Reading is terminated as soon as | ||
254 | .Xr BIO_gets 3 | ||
255 | returns a value less than 1. | ||