1=pod 2 3=head1 NAME 4 5ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, 6ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio, 7ASN1_item_pack, ASN1_item_unpack_ex, ASN1_item_unpack 8- decode and encode DER-encoded ASN.1 structures 9 10=head1 SYNOPSIS 11 12 #include <openssl/asn1.h> 13 14 ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, 15 long len, const ASN1_ITEM *it, 16 OSSL_LIB_CTX *libctx, const char *propq); 17 ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **pval, const unsigned char **in, 18 long len, const ASN1_ITEM *it); 19 20 void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *x, 21 OSSL_LIB_CTX *libctx, const char *propq); 22 void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *x); 23 24 void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x, 25 OSSL_LIB_CTX *libctx, const char *propq); 26 void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x); 27 28 BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val); 29 30 ASN1_STRING *ASN1_item_pack(void *obj, const ASN1_ITEM *it, ASN1_STRING **oct); 31 32 void *ASN1_item_unpack(const ASN1_STRING *oct, const ASN1_ITEM *it); 33 34 void *ASN1_item_unpack_ex(const ASN1_STRING *oct, const ASN1_ITEM *it, 35 OSSL_LIB_CTX *libctx, const char *propq); 36 37=head1 DESCRIPTION 38 39ASN1_item_d2i_ex() decodes the contents of the data stored in I<*in> of length 40I<len> which must be a DER-encoded ASN.1 structure, using the ASN.1 template 41I<it>. It places the result in I<*pval> unless I<pval> is NULL. If I<*pval> is 42non-NULL on entry then the B<ASN1_VALUE> present there will be reused. Otherwise 43a new B<ASN1_VALUE> will be allocated. If any algorithm fetches are required 44during the process then they will use the B<OSSL_LIB_CTX>provided in the 45I<libctx> parameter and the property query string in I<propq>. See 46L<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching. 47On exit I<*in> will be updated to point to the next byte in the buffer after the 48decoded structure. 49 50ASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default 51OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string. 52 53ASN1_item_d2i_bio_ex() decodes the contents of its input BIO I<in>, 54which must be a DER-encoded ASN.1 structure, using the ASN.1 template I<it> 55and places the result in I<*pval> unless I<pval> is NULL. 56If I<in> is NULL it returns NULL, else a pointer to the parsed structure. If any 57algorithm fetches are required during the process then they will use the 58B<OSSL_LIB_CTX> provided in the I<libctx> parameter and the property query 59string in I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for more information 60about algorithm fetching. 61 62ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the 63default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query 64string. 65 66ASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE 67pointer is provided instead of a BIO. 68 69ASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the 70default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query 71string. 72 73ASN1_item_i2d_mem_bio() encodes the given ASN.1 value I<val> 74using the ASN.1 template I<it> and returns the result in a memory BIO. 75 76ASN1_item_pack() encodes the given ASN.1 value in I<obj> using the 77ASN.1 template I<it> and returns an B<ASN1_STRING> object. If the passed in 78I<*oct> is not NULL then this is used to store the returned result, otherwise 79a new B<ASN1_STRING> object is created. If I<oct> is not NULL and I<*oct> is NULL 80then the returned return is also set into I<*oct>. If there is an error the optional 81passed in B<ASN1_STRING> will not be freed, but the previous value may be cleared when 82ASN1_STRING_set0(*oct, NULL, 0) is called internally. 83 84ASN1_item_unpack() uses ASN1_item_d2i() to decode the DER-encoded B<ASN1_STRING> 85I<oct> using the ASN.1 template I<it>. 86 87ASN1_item_unpack_ex() is similar to ASN1_item_unpack(), but uses ASN1_item_d2i_ex() so 88that the I<libctx> and I<propq> can be used when doing algorithm fetching. 89 90=head1 RETURN VALUES 91 92ASN1_item_d2i_bio(), ASN1_item_unpack_ex() and ASN1_item_unpack() return a pointer to 93an B<ASN1_VALUE> or NULL on error. 94 95ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error. 96 97ASN1_item_pack() returns a pointer to an B<ASN1_STRING> or NULL on error. 98 99=head1 HISTORY 100 101The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex() 102and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0. 103 104The function ASN1_item_unpack_ex() was added in OpenSSL 3.2. 105 106=head1 COPYRIGHT 107 108Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved. 109 110Licensed under the Apache License 2.0 (the "License"). You may not use 111this file except in compliance with the License. You can obtain a copy 112in the file LICENSE in the source distribution or at 113L<https://www.openssl.org/source/license.html>. 114 115=cut 116
