2
0

ASN1_item_d2i_bio.pod 4.9 KB

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