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