]>
Commit | Line | Data |
---|---|---|
6c5b6cb0 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
8162f6f5 | 5 | ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, |
3ba4dac6 RS |
6 | ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN |
7 | - ASN.1 INTEGER and ENUMERATED utilities | |
6c5b6cb0 DSH |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/asn1.h> | |
12 | ||
13 | int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a); | |
eaf39a9f | 14 | long ASN1_INTEGER_get(const ASN1_INTEGER *a); |
6c5b6cb0 DSH |
15 | |
16 | int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r); | |
eaf39a9f | 17 | int ASN1_INTEGER_set(const ASN1_INTEGER *a, long v); |
6c5b6cb0 | 18 | |
c5f28105 DSH |
19 | int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a); |
20 | int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r); | |
21 | ||
6c5b6cb0 DSH |
22 | ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai); |
23 | BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn); | |
24 | ||
2aa28a1a | 25 | int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a); |
f48ebf9f | 26 | long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a); |
6c5b6cb0 | 27 | |
2aa28a1a | 28 | int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r); |
6c5b6cb0 DSH |
29 | int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v); |
30 | ||
31 | ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai); | |
32 | BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn); | |
33 | ||
34 | =head1 DESCRIPTION | |
35 | ||
36 | These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED> | |
37 | structures. | |
38 | ||
39 | ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type | |
723e9c89 | 40 | If successful it returns 1 and sets I<*pr> to the value of I<a>. If it fails |
6c5b6cb0 DSH |
41 | (due to invalid type or the value being too big to fit into an B<int64_t> type) |
42 | it returns 0. | |
43 | ||
c5f28105 DSH |
44 | ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it |
45 | converts to a B<uint64_t> type and an error is returned if the passed integer | |
46 | is negative. | |
47 | ||
723e9c89 | 48 | ASN1_INTEGER_get() also returns the value of I<a> but it returns 0 if I<a> is |
6c5b6cb0 DSH |
49 | NULL and -1 on error (which is ambiguous because -1 is a legitimate value for |
50 | an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64() | |
51 | instead. | |
52 | ||
723e9c89 RL |
53 | ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> I<a> to the |
54 | B<int64_t> value I<r>. | |
6c5b6cb0 | 55 | |
723e9c89 RL |
56 | ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> I<a> to the |
57 | B<uint64_t> value I<r>. | |
c5f28105 | 58 | |
723e9c89 RL |
59 | ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> I<a> to the I<long> value |
60 | I<v>. | |
6c5b6cb0 | 61 | |
723e9c89 RL |
62 | BN_to_ASN1_INTEGER() converts B<BIGNUM> I<bn> to an B<ASN1_INTEGER>. If I<ai> |
63 | is NULL a new B<ASN1_INTEGER> structure is returned. If I<ai> is not NULL then | |
6c5b6cb0 DSH |
64 | the existing structure will be used instead. |
65 | ||
723e9c89 RL |
66 | ASN1_INTEGER_to_BN() converts ASN1_INTEGER I<ai> into a B<BIGNUM>. If I<bn> is |
67 | NULL a new B<BIGNUM> structure is returned. If I<bn> is not NULL then the | |
6c5b6cb0 DSH |
68 | existing structure will be used instead. |
69 | ||
70 | ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(), | |
71 | ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN() | |
72 | behave in an identical way to their ASN1_INTEGER counterparts except they | |
73 | operate on an B<ASN1_ENUMERATED> value. | |
74 | ||
723e9c89 RL |
75 | ASN1_ENUMERATED_get() returns the value of I<a> in a similar way to |
76 | ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of I<a> will not | |
6c5b6cb0 DSH |
77 | fit in a long type. New applications should use ASN1_ENUMERATED_get_int64() |
78 | instead. | |
79 | ||
80 | =head1 NOTES | |
81 | ||
82 | In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an | |
83 | integer of almost arbitrary size and so cannot always be represented by a C | |
8c1cbc72 | 84 | B<int64_t> type. However, in many cases (for example version numbers) they |
6c5b6cb0 DSH |
85 | represent small integers which can be more easily manipulated if converted to |
86 | an appropriate C integer type. | |
87 | ||
88 | =head1 BUGS | |
89 | ||
0d4fb843 | 90 | The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() |
6c5b6cb0 | 91 | mean these functions should be avoided if possible. They are retained for |
0d4fb843 | 92 | compatibility. Normally the ambiguous return values are not legitimate |
6c5b6cb0 DSH |
93 | values for the fields they represent. |
94 | ||
95 | =head1 RETURN VALUES | |
96 | ||
97 | ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and | |
98 | ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only | |
99 | fail if a memory allocation error occurs. | |
100 | ||
101 | ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success | |
102 | and 0 for failure. They will fail if the passed type is incorrect (this will | |
103 | only happen if there is a programming error) or if the value exceeds the range | |
104 | of an B<int64_t> type. | |
105 | ||
106 | BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or | |
107 | B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will | |
108 | only fail due to a memory allocation error. | |
109 | ||
110 | ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure | |
35ed393e | 111 | of NULL if an error occurs. They can fail if the passed type is incorrect |
6c5b6cb0 DSH |
112 | (due to programming error) or due to a memory allocation failure. |
113 | ||
114 | =head1 SEE ALSO | |
115 | ||
9b86974e | 116 | L<ERR_get_error(3)> |
6c5b6cb0 DSH |
117 | |
118 | =head1 HISTORY | |
119 | ||
120 | ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(), | |
121 | ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64() | |
fc5ecadd | 122 | were added in OpenSSL 1.1.0. |
6c5b6cb0 | 123 | |
e2f92610 RS |
124 | =head1 COPYRIGHT |
125 | ||
1212818e | 126 | Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 127 | |
4746f25a | 128 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
129 | this file except in compliance with the License. You can obtain a copy |
130 | in the file LICENSE in the source distribution or at | |
131 | L<https://www.openssl.org/source/license.html>. | |
132 | ||
133 | =cut |