1ASN1_EXTERN_FUNCS(3ossl)            OpenSSL           ASN1_EXTERN_FUNCS(3ossl)
2
3
4

NAME

6       ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d,
7       ASN1_ex_new_func, ASN1_ex_new_ex_func, ASN1_ex_free_func,
8       ASN1_ex_print_func, IMPLEMENT_EXTERN_ASN1 - ASN.1 external function
9       support
10

SYNOPSIS

12        #include <openssl/asn1t.h>
13
14        typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,
15                                const ASN1_ITEM *it, int tag, int aclass, char opt,
16                                ASN1_TLC *ctx);
17        typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,
18                                   const ASN1_ITEM *it, int tag, int aclass, char opt,
19                                   ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,
20                                   const char *propq);
21        typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,
22                                const ASN1_ITEM *it, int tag, int aclass);
23        typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
24        typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,
25                                        OSSL_LIB_CTX *libctx, const char *propq);
26        typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
27        typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,
28                                       int indent, const char *fname,
29                                       const ASN1_PCTX *pctx);
30
31        struct ASN1_EXTERN_FUNCS_st {
32           void *app_data;
33           ASN1_ex_new_func *asn1_ex_new;
34           ASN1_ex_free_func *asn1_ex_free;
35           ASN1_ex_free_func *asn1_ex_clear;
36           ASN1_ex_d2i *asn1_ex_d2i;
37           ASN1_ex_i2d *asn1_ex_i2d;
38           ASN1_ex_print_func *asn1_ex_print;
39           ASN1_ex_new_ex_func *asn1_ex_new_ex;
40           ASN1_ex_d2i_ex *asn1_ex_d2i_ex;
41        };
42        typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;
43
44        #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)
45

DESCRIPTION

47       ASN.1 data structures templates are typically defined in OpenSSL using
48       a series of macros such as ASN1_SEQUENCE(), ASN1_SEQUENCE_END() and so
49       on. Instead templates can also be defined based entirely on external
50       functions. These external functions are called to perform operations
51       such as creating a new ASN1_VALUE or converting an ASN1_VALUE to or
52       from DER encoding.
53
54       The macro IMPLEMENT_EXTERN_ASN1() can be used to create such an
55       externally defined structure. The name of the structure should be
56       supplied in the sname parameter. The tag for the structure (e.g.
57       typically V_ASN1_SEQUENCE) should be supplied in the tag parameter.
58       Finally a pointer to an ASN1_EXTERN_FUNCS structure should be supplied
59       in the fptrs parameter.
60
61       The ASN1_EXTERN_FUNCS structure has the following entries.
62
63       app_data
64           A pointer to arbitrary application specific data.
65
66       asn1_ex_new
67           A "new" function responsible for constructing a new ASN1_VALUE
68           object. The newly constructed value should be stored in *pval. The
69           it parameter is a pointer to the ASN1_ITEM template object created
70           via the IMPLEMENT_EXTERN_ASN1() macro.
71
72           Returns a positive value on success or 0 on error.
73
74       asn1_ex_free
75           A "free" function responsible for freeing the ASN1_VALUE passed in
76           *pval that was previously allocated via a "new" function. The it
77           parameter is a pointer to the ASN1_ITEM template object created via
78           the IMPLEMENT_EXTERN_ASN1() macro.
79
80       asn1_ex_clear
81           A "clear" function responsible for clearing any data in the
82           ASN1_VALUE passed in *pval and making it suitable for reuse. The it
83           parameter is a pointer to the ASN1_ITEM template object created via
84           the IMPLEMENT_EXTERN_ASN1() macro.
85
86       asn1_ex_d2i
87           A "d2i" function responsible for converting DER data with the tag
88           tag and class class into an ASN1_VALUE. If *pval is non-NULL then
89           the ASN_VALUE it points to should be reused. Otherwise a new
90           ASN1_VALUE should be allocated and stored in *pval. *in points to
91           the DER data to be decoded and len is the length of that data.
92           After decoding *in should be updated to point at the next byte
93           after the decoded data. If the ASN1_VALUE is considered optional in
94           this context then opt will be nonzero. Otherwise it will be zero.
95           The it parameter is a pointer to the ASN1_ITEM template object
96           created via the IMPLEMENT_EXTERN_ASN1() macro. A pointer to the
97           current ASN1_TLC context (which may be required for other ASN1
98           function calls) is passed in the ctx parameter.
99
100           The asn1_ex_d2i entry may be NULL if asn1_ex_d2i_ex has been
101           specified instead.
102
103           Returns <= 0 on error or a positive value on success.
104
105       asn1_ex_i2d
106           An "i2d" function responsible for converting an ASN1_VALUE into DER
107           encoding.  On entry *pval will contain the ASN1_VALUE to be
108           encoded. If default tagging is to be used then tag will be -1 on
109           entry. Otherwise if implicit tagging should be used then tag and
110           aclass will be the tag and associated class.
111
112           If out is not NULL then this function should write the DER encoded
113           data to the buffer in *out, and then increment *out to point to
114           immediately after the data just written.
115
116           If out is NULL then no data should be written but the length
117           calculated and returned as if it were.
118
119           The asn1_ex_i2d entry may be NULL if asn1_ex_i2d_ex has been
120           specified instead.
121
122           The return value should be negative if a fatal error occurred, or 0
123           if a non-fatal error occurred. Otherwise it should return the
124           length of the encoded data.
125
126       asn1_ex_print
127           A "print" function. out is the BIO to print the output to. *pval is
128           the ASN1_VALUE to be printed. indent is the number of spaces of
129           indenting to be printed before any data is printed. fname is
130           currently unused and is always "". pctx is a pointer to the
131           ASN1_PCTX for the print operation.
132
133           Returns 0 on error or a positive value on success. If the return
134           value is 2 then an additional newline will be printed after the
135           data printed by this function.
136
137       asn1_ex_new_ex
138           This is the same as asn1_ex_new except that it is additionally
139           passed the OSSL_LIB_CTX to be used in libctx and any property query
140           string to be used for algorithm fetching in the propq parameter.
141           See "ALGORITHM FETCHING" in crypto(7) for further details. If
142           asn1_ex_new_ex is non NULL, then it will always be called in
143           preference to asn1_ex_new.
144
145       asn1_ex_d2i_ex
146           This is the same as asn1_ex_d2i except that it is additionally
147           passed the OSSL_LIB_CTX to be used in libctx and any property query
148           string to be used for algorithm fetching in the propq parameter.
149           See "ALGORITHM FETCHING" in crypto(7) for further details. If
150           asn1_ex_d2i_ex is non NULL, then it will always be called in
151           preference to asn1_ex_d2i.
152

RETURN VALUES

154       Return values for the various callbacks are as described above.
155

SEE ALSO

157       ASN1_item_new_ex(3)
158

HISTORY

160       The asn1_ex_new_ex and asn1_ex_d2i_ex callbacks were added in OpenSSL
161       3.0.
162
164       Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
165
166       Licensed under the Apache License 2.0 (the "License").  You may not use
167       this file except in compliance with the License.  You can obtain a copy
168       in the file LICENSE in the source distribution or at
169       <https://www.openssl.org/source/license.html>.
170
171
172
1733.0.5                             2022-07-05          ASN1_EXTERN_FUNCS(3ossl)
Impressum