xref: /freebsd/crypto/openssl/doc/man3/ASN1_item_d2i_bio.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre Pronchery=pod
2*b077aed3SPierre Pronchery
3*b077aed3SPierre Pronchery=head1 NAME
4*b077aed3SPierre Pronchery
5*b077aed3SPierre ProncheryASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio,
6*b077aed3SPierre ProncheryASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio
7*b077aed3SPierre Pronchery- decode and encode DER-encoded ASN.1 structures
8*b077aed3SPierre Pronchery
9*b077aed3SPierre Pronchery=head1 SYNOPSIS
10*b077aed3SPierre Pronchery
11*b077aed3SPierre Pronchery #include <openssl/asn1.h>
12*b077aed3SPierre Pronchery
13*b077aed3SPierre Pronchery ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in,
14*b077aed3SPierre Pronchery                              long len, const ASN1_ITEM *it,
15*b077aed3SPierre Pronchery                              OSSL_LIB_CTX *libctx, const char *propq);
16*b077aed3SPierre Pronchery ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in,
17*b077aed3SPierre Pronchery                           long len, const ASN1_ITEM *it);
18*b077aed3SPierre Pronchery
19*b077aed3SPierre Pronchery void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x,
20*b077aed3SPierre Pronchery                            OSSL_LIB_CTX *libctx, const char *propq);
21*b077aed3SPierre Pronchery void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x);
22*b077aed3SPierre Pronchery
23*b077aed3SPierre Pronchery void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,
24*b077aed3SPierre Pronchery                           OSSL_LIB_CTX *libctx, const char *propq);
25*b077aed3SPierre Pronchery void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
26*b077aed3SPierre Pronchery
27*b077aed3SPierre Pronchery BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);
28*b077aed3SPierre Pronchery
29*b077aed3SPierre Pronchery=head1 DESCRIPTION
30*b077aed3SPierre Pronchery
31*b077aed3SPierre ProncheryASN1_item_d2i_ex() decodes the contents of the data stored in I<*in> of length
32*b077aed3SPierre ProncheryI<len> which must be a DER-encoded ASN.1 structure, using the ASN.1 template
33*b077aed3SPierre ProncheryI<it>. It places the result in I<*pval> unless I<pval> is NULL. If I<*pval> is
34*b077aed3SPierre Proncherynon-NULL on entry then the B<ASN1_VALUE> present there will be reused. Otherwise
35*b077aed3SPierre Proncherya new B<ASN1_VALUE> will be allocated. If any algorithm fetches are required
36*b077aed3SPierre Proncheryduring the process then they will use the B<OSSL_LIB_CTX>provided in the
37*b077aed3SPierre ProncheryI<libctx> parameter and the property query string in I<propq>. See
38*b077aed3SPierre ProncheryL<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching.
39*b077aed3SPierre ProncheryOn exit I<*in> will be updated to point to the next byte in the buffer after the
40*b077aed3SPierre Proncherydecoded structure.
41*b077aed3SPierre Pronchery
42*b077aed3SPierre ProncheryASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default
43*b077aed3SPierre ProncheryOSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.
44*b077aed3SPierre Pronchery
45*b077aed3SPierre ProncheryASN1_item_d2i_bio_ex() decodes the contents of its input BIO I<in>,
46*b077aed3SPierre Proncherywhich must be a DER-encoded ASN.1 structure, using the ASN.1 template I<it>
47*b077aed3SPierre Proncheryand places the result in I<*pval> unless I<pval> is NULL.
48*b077aed3SPierre ProncheryIf I<in> is NULL it returns NULL, else a pointer to the parsed structure. If any
49*b077aed3SPierre Proncheryalgorithm fetches are required during the process then they will use the
50*b077aed3SPierre ProncheryB<OSSL_LIB_CTX> provided in the I<libctx> parameter and the property query
51*b077aed3SPierre Proncherystring in I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for more information
52*b077aed3SPierre Proncheryabout algorithm fetching.
53*b077aed3SPierre Pronchery
54*b077aed3SPierre ProncheryASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the
55*b077aed3SPierre Proncherydefault B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query
56*b077aed3SPierre Proncherystring.
57*b077aed3SPierre Pronchery
58*b077aed3SPierre ProncheryASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE
59*b077aed3SPierre Proncherypointer is provided instead of a BIO.
60*b077aed3SPierre Pronchery
61*b077aed3SPierre ProncheryASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the
62*b077aed3SPierre Proncherydefault B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query
63*b077aed3SPierre Proncherystring.
64*b077aed3SPierre Pronchery
65*b077aed3SPierre ProncheryASN1_item_i2d_mem_bio() encodes the given ASN.1 value I<val>
66*b077aed3SPierre Proncheryusing the ASN.1 template I<it> and returns the result in a memory BIO.
67*b077aed3SPierre Pronchery
68*b077aed3SPierre Pronchery=head1 RETURN VALUES
69*b077aed3SPierre Pronchery
70*b077aed3SPierre ProncheryASN1_item_d2i_bio() returns a pointer to an B<ASN1_VALUE> or NULL.
71*b077aed3SPierre Pronchery
72*b077aed3SPierre ProncheryASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error.
73*b077aed3SPierre Pronchery
74*b077aed3SPierre Pronchery=head1 HISTORY
75*b077aed3SPierre Pronchery
76*b077aed3SPierre ProncheryThe functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex()
77*b077aed3SPierre Proncheryand ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0.
78*b077aed3SPierre Pronchery
79*b077aed3SPierre Pronchery=head1 COPYRIGHT
80*b077aed3SPierre Pronchery
81*b077aed3SPierre ProncheryCopyright 2021 The OpenSSL Project Authors. All Rights Reserved.
82*b077aed3SPierre Pronchery
83*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License").  You may not use
84*b077aed3SPierre Proncherythis file except in compliance with the License.  You can obtain a copy
85*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at
86*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>.
87*b077aed3SPierre Pronchery
88*b077aed3SPierre Pronchery=cut
89