]>
Commit | Line | Data |
---|---|---|
dd14f911 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
22f5bd3d | 5 | ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility |
dd14f911 DSH |
6 | functions |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/asn1.h> | |
11 | ||
08275a29 | 12 | int ASN1_TYPE_get(const ASN1_TYPE *a); |
dd14f911 DSH |
13 | void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value); |
14 | int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value); | |
15 | int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b); | |
16 | ||
22f5bd3d DSH |
17 | void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t); |
18 | ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s, | |
19 | ASN1_TYPE **t); | |
20 | ||
dd14f911 DSH |
21 | =head1 DESCRIPTION |
22 | ||
23 | These functions allow an ASN1_TYPE structure to be manipulated. The | |
24 | ASN1_TYPE structure can contain any ASN.1 type or constructed type | |
25 | such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. | |
26 | ||
27 | ASN1_TYPE_get() returns the type of B<a>. | |
28 | ||
29 | ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This | |
30 | function uses the pointer B<value> internally so it must B<not> be freed | |
31 | up after the call. | |
32 | ||
33 | ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>. | |
34 | ||
35 | ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if | |
36 | they are identical and non-zero otherwise. | |
37 | ||
22f5bd3d DSH |
38 | ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in |
39 | B<t> using the ASN.1 structure B<it>. If successful it returns a pointer | |
40 | to the ASN.1 structure corresponding to B<it> which must be freed by the | |
41 | caller. If it fails it return NULL. | |
42 | ||
43 | ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s> | |
44 | corresponding to B<it> into an ASN1_TYPE. If successful the encoded | |
45 | ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type | |
46 | is written to B<t> overwriting any existing data. If B<t> is not NULL | |
47 | but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>. | |
48 | ||
dd14f911 DSH |
49 | =head1 NOTES |
50 | ||
51 | The type and meaning of the B<value> parameter for ASN1_TYPE_set() and | |
52 | ASN1_TYPE_set1() is determined by the B<type> parameter. | |
53 | If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN | |
54 | then the boolean is set to TRUE if B<value> is not NULL. If B<type> is | |
55 | V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type> | |
56 | is and ASN1_STRING structure. If B<type> corresponds to a primitive type | |
57 | (or a string type) then the contents of the ASN1_STRING contain the content | |
58 | octets of the type. If B<type> corresponds to a constructed type or | |
59 | a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the | |
60 | ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and | |
61 | length octets). | |
62 | ||
63 | ASN1_TYPE_cmp() may not return zero if two types are equivalent but have | |
64 | different encodings. For example the single content octet of the boolean TRUE | |
65 | value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will | |
66 | only return zero if the values are the same. | |
67 | ||
68 | If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the | |
69 | return value is non-zero. Technically if both parameters are NULL the two | |
70 | types could be absent OPTIONAL fields and so should match, however passing | |
71 | NULL values could also indicate a programming error (for example an | |
72 | unparseable type which returns NULL) for types which do B<not> match. So | |
73 | applications should handle the case of two absent values separately. | |
74 | ||
75 | =head1 RETURN VALUES | |
76 | ||
77 | ASN1_TYPE_get() returns the type of the ASN1_TYPE argument. | |
78 | ||
79 | ASN1_TYPE_set() does not return a value. | |
80 | ||
186bb907 | 81 | ASN1_TYPE_set1() returns 1 for success and 0 for failure. |
dd14f911 DSH |
82 | |
83 | ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise. | |
84 | ||
22f5bd3d DSH |
85 | ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or |
86 | NULL on failure. | |
87 | ||
88 | ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or | |
89 | NULL on failure. | |
90 | ||
e2f92610 RS |
91 | =head1 COPYRIGHT |
92 | ||
93 | Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. | |
94 | ||
4746f25a | 95 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
96 | this file except in compliance with the License. You can obtain a copy |
97 | in the file LICENSE in the source distribution or at | |
98 | L<https://www.openssl.org/source/license.html>. | |
99 | ||
100 | =cut |