doc/man3/ASN1_item_d2i_bio.pod

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