summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_INTEGER_get.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ASN1_INTEGER_get.3')
-rw-r--r--src/lib/libcrypto/man/ASN1_INTEGER_get.3428
1 files changed, 0 insertions, 428 deletions
diff --git a/src/lib/libcrypto/man/ASN1_INTEGER_get.3 b/src/lib/libcrypto/man/ASN1_INTEGER_get.3
deleted file mode 100644
index 84f566eda9..0000000000
--- a/src/lib/libcrypto/man/ASN1_INTEGER_get.3
+++ /dev/null
@@ -1,428 +0,0 @@
1.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.7 2023/05/22 19:38:04 tb Exp $
2.\" selective merge up to:
3.\" OpenSSL man3/ASN1_INTEGER_get_int64 24a535ea Sep 22 13:14:20 2020 +0100
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2018, 2021, 2022 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
23.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: May 22 2023 $
70.Dt ASN1_INTEGER_GET 3
71.Os
72.Sh NAME
73.Nm ASN1_INTEGER_get_uint64 ,
74.Nm ASN1_INTEGER_get_int64 ,
75.Nm ASN1_INTEGER_get ,
76.Nm ASN1_INTEGER_set_uint64 ,
77.Nm ASN1_INTEGER_set_int64 ,
78.Nm ASN1_INTEGER_set ,
79.Nm ASN1_INTEGER_cmp ,
80.Nm ASN1_INTEGER_dup ,
81.Nm BN_to_ASN1_INTEGER ,
82.Nm ASN1_INTEGER_to_BN ,
83.Nm ASN1_ENUMERATED_get_int64 ,
84.Nm ASN1_ENUMERATED_get ,
85.Nm ASN1_ENUMERATED_set_int64 ,
86.Nm ASN1_ENUMERATED_set ,
87.Nm BN_to_ASN1_ENUMERATED ,
88.Nm ASN1_ENUMERATED_to_BN
89.Nd ASN.1 INTEGER and ENUMERATED utilities
90.Sh SYNOPSIS
91.In openssl/asn1.h
92.Ft int
93.Fo ASN1_INTEGER_get_uint64
94.Fa "uint64_t *out_val"
95.Fa "const ASN1_INTEGER *a"
96.Fc
97.Ft int
98.Fo ASN1_INTEGER_get_int64
99.Fa "int64_t *out_val"
100.Fa "const ASN1_INTEGER *a"
101.Fc
102.Ft long
103.Fo ASN1_INTEGER_get
104.Fa "const ASN1_INTEGER *a"
105.Fc
106.Ft int
107.Fo ASN1_INTEGER_set_uint64
108.Fa "ASN1_INTEGER *a"
109.Fa "uint64_t v"
110.Fc
111.Ft int
112.Fo ASN1_INTEGER_set_int64
113.Fa "ASN1_INTEGER *a"
114.Fa "int64_t v"
115.Fc
116.Ft int
117.Fo ASN1_INTEGER_set
118.Fa "ASN1_INTEGER *a"
119.Fa "long v"
120.Fc
121.Ft int
122.Fo ASN1_INTEGER_cmp
123.Fa "const ASN1_INTEGER *a1"
124.Fa "const ASN1_INTEGER *a2"
125.Fc
126.Ft ASN1_INTEGER *
127.Fo ASN1_INTEGER_dup
128.Fa "const ASN1_INTEGER *a"
129.Fc
130.Ft ASN1_INTEGER *
131.Fo BN_to_ASN1_INTEGER
132.Fa "const BIGNUM *bn"
133.Fa "ASN1_INTEGER *ai"
134.Fc
135.Ft BIGNUM *
136.Fo ASN1_INTEGER_to_BN
137.Fa "const ASN1_INTEGER *ai"
138.Fa "BIGNUM *bn"
139.Fc
140.Ft int
141.Fo ASN1_ENUMERATED_get_int64
142.Fa "int64_t *out_val"
143.Fa "const ASN1_ENUMERATED *a"
144.Fc
145.Ft long
146.Fo ASN1_ENUMERATED_get
147.Fa "const ASN1_ENUMERATED *a"
148.Fc
149.Ft int
150.Fo ASN1_ENUMERATED_set_int64
151.Fa "ASN1_ENUMERATED *a"
152.Fa "int64_t v"
153.Fc
154.Ft int
155.Fo ASN1_ENUMERATED_set
156.Fa "ASN1_ENUMERATED *a"
157.Fa "long v"
158.Fc
159.Ft ASN1_ENUMERATED *
160.Fo BN_to_ASN1_ENUMERATED
161.Fa "const BIGNUM *bn"
162.Fa "ASN1_ENUMERATED *ai"
163.Fc
164.Ft BIGNUM *
165.Fo ASN1_ENUMERATED_to_BN
166.Fa "const ASN1_ENUMERATED *ai"
167.Fa "BIGNUM *bn"
168.Fc
169.Sh DESCRIPTION
170These functions convert to and from
171.Vt ASN1_INTEGER
172and
173.Vt ASN1_ENUMERATED
174objects.
175.Pp
176.Fn ASN1_INTEGER_get_uint64
177and
178.Fn ASN1_INTEGER_get_int64
179store the value of
180.Fa a
181in
182.Pf * Fa out_val
183if successful.
184.Pp
185The deprecated function
186.Fn ASN1_INTEGER_get
187converts
188.Fa a
189to the
190.Vt long
191type.
192.Pp
193.Fn ASN1_INTEGER_set_uint64 ,
194.Fn ASN1_INTEGER_set_int64 ,
195and
196.Fn ASN1_INTEGER_set
197set the type of
198.Fa a
199to
200.Dv V_ASN1_INTEGER
201or
202.Dv V_ASN1_NEG_INTEGER
203depending on the sign of
204.Fa v
205and set the value of
206.Fa a
207to
208.Fa v .
209.Pp
210.Fn ASN1_INTEGER_cmp
211compares the signed integer numbers represented by
212.Fa a1
213and
214.Fa a2 .
215.Pp
216.Fn ASN1_INTEGER_dup
217does exactly the same as
218.Xr ASN1_STRING_dup 3
219without providing any type safety,
220except that it fails if the
221.Xr ASN1_STRING_length 3
222of
223.Fa a
224is 0.
225.Pp
226.Fn BN_to_ASN1_INTEGER
227converts
228.Fa bn
229to an
230.Vt ASN1_INTEGER .
231If
232.Fa ai
233is
234.Dv NULL ,
235a new
236.Vt ASN1_INTEGER
237object is returned.
238Otherwise, the existing object
239.Fa ai
240is used instead.
241.Pp
242.Fn ASN1_INTEGER_to_BN
243converts
244.Fa ai
245into a
246.Vt BIGNUM .
247If
248.Fa bn
249is
250.Dv NULL ,
251a new
252.Vt BIGNUM
253object is returned.
254Otherwise, the existing object
255.Fa bn
256is used instead.
257.Pp
258.Fn ASN1_ENUMERATED_get_int64 ,
259.Fn ASN1_ENUMERATED_get ,
260.Fn ASN1_ENUMERATED_set_int64 ,
261.Fn ASN1_ENUMERATED_set ,
262.Fn BN_to_ASN1_ENUMERATED ,
263and
264.Fn ASN1_ENUMERATED_to_BN
265behave like their
266.Vt ASN1_INTEGER
267counterparts except that they operate on an
268.Vt ASN1_ENUMERATED
269object.
270.Sh RETURN VALUES
271.Fn ASN1_INTEGER_get_uint64
272returns 1 in case of success or 0 if
273.Fa a
274is not of the type
275.Dv V_ASN1_INTEGER
276or greater than
277.Dv UINT64_MAX .
278.Pp
279.Fn ASN1_INTEGER_get_int64
280returns 1 in case of success or 0 if
281.Fa a
282is not of the type
283.Dv V_ASN1_INTEGER
284or
285.Dv V_ASN1_NEG_INTEGER ,
286less than
287.Dv INT64_MIN ,
288or greater than
289.Dv INT64_MAX .
290.Pp
291.Fn ASN1_INTEGER_get
292and
293.Fn ASN1_ENUMERATED_get
294return the converted value, 0 if
295.Fa a
296is
297.Dv NULL ,
298or \-1 on error, which is ambiguous because \-1 is a legitimate
299value for an
300.Vt ASN1_INTEGER .
301.Pp
302.Fn ASN1_INTEGER_set_uint64 ,
303.Fn ASN1_INTEGER_set_int64 ,
304.Fn ASN1_INTEGER_set ,
305.Fn ASN1_ENUMERATED_set_int64 ,
306and
307.Fn ASN1_ENUMERATED_set
308return 1 for success or 0 for failure.
309They only fail if a memory allocation error occurs.
310.Pp
311.Fn ASN1_INTEGER_cmp
312returns a value greater than, equal to, or less than 0
313if the signed integer number represented by
314.Fa a1
315is greater than, equal to, or less than
316the signed integer number represented by
317.Fa a2 ,
318respectively.
319.Pp
320.Fn ASN1_INTEGER_dup
321returns a pointer to a newly allocated
322.Vt ASN1_STRING
323structure or
324.Dv NULL
325if
326.Fa a
327is a
328.Dv NULL
329pointer, if the length of
330.Fa a
331is 0, or if memory allocation fails.
332.Pp
333.Fn BN_to_ASN1_INTEGER
334and
335.Fn BN_to_ASN1_ENUMERATED
336return an
337.Vt ASN1_INTEGER
338or
339.Vt ASN1_ENUMERATED
340object, respectively, or
341.Dv NULL
342if an error occurs.
343They only fail due to memory allocation errors.
344.Pp
345.Fn ASN1_INTEGER_to_BN
346and
347.Fn ASN1_ENUMERATED_to_BN
348return a
349.Vt BIGNUM
350object of
351.Dv NULL
352if an error occurs.
353They can fail if the passed type is incorrect (due to a programming error)
354or due to memory allocation failures.
355.Sh SEE ALSO
356.Xr ASN1_INTEGER_new 3 ,
357.Xr ASN1_STRING_length 3
358.Sh HISTORY
359.Fn ASN1_INTEGER_set
360first appeared in SSLeay 0.5.1.
361.Fn ASN1_INTEGER_get ,
362.Fn BN_to_ASN1_INTEGER ,
363and
364.Fn ASN1_INTEGER_to_BN
365first appeared in SSLeay 0.6.0.
366.Fn ASN1_INTEGER_cmp
367and
368.Fn ASN1_INTEGER_dup
369first appeared in SSLeay 0.6.5.
370These functions have been available since
371.Ox 2.3 .
372.Pp
373.Fn ASN1_ENUMERATED_get ,
374.Fn ASN1_ENUMERATED_set ,
375.Fn BN_to_ASN1_ENUMERATED ,
376and
377.Fn ASN1_ENUMERATED_to_BN
378first appeared in OpenSSL 0.9.2b and have been available since
379.Ox 2.6 .
380.Pp
381.Fn ASN1_INTEGER_get_uint64 ,
382.Fn ASN1_INTEGER_get_int64 ,
383.Fn ASN1_INTEGER_set_uint64 ,
384.Fn ASN1_INTEGER_set_int64 ,
385.Fn ASN1_ENUMERATED_get_int64 ,
386and
387.Fn ASN1_ENUMERATED_set_int64
388first appeared in OpenSSL 1.1.0 and have been available since
389.Ox 7.2 .
390.Sh CAVEATS
391In general an
392.Vt ASN1_INTEGER
393or
394.Vt ASN1_ENUMERATED
395type can contain an integer of almost arbitrary size
396and so cannot always be represented by a C
397.Vt long
398type.
399The ambiguous return values of
400.Fn ASN1_INTEGER_get
401and
402.Fn ASN1_ENUMERATED_get
403imply that these functions should be avoided if possible.
404.Sh BUGS
405.Fn ASN1_INTEGER_cmp ,
406.Fn ASN1_INTEGER_dup ,
407and
408.Fn ASN1_INTEGER_to_BN
409do not check whether their arguments are really of the type
410.Dv V_ASN1_INTEGER
411or
412.Dv V_ASN1_NEG_INTEGER .
413They may report success even if their arguments are of a wrong type.
414Consequently, even in case of success, the return value of
415.Fn ASN1_INTEGER_dup
416is not guaranteed to be of the type
417.Dv V_ASN1_INTEGER
418or
419.Dv V_ASN1_NEG_INTEGER
420either.
421.Pp
422Similarly,
423.Fn ASN1_ENUMERATED_to_BN
424does not check whether its argument is really of the type
425.Dv V_ASN1_ENUMERATED
426or
427.Dv V_ASN1_NEG_ENUMERATED
428and may report success even if the argument is of a wrong type.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-05-06 18:15:28 +0000