diff options
author | Matt Caswell <matt@openssl.org> | 2021-06-01 15:17:38 +0100 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2021-06-05 17:39:27 +1000 |
commit | 3d9d1ce52904660757dadeb629926932abe25158 (patch) | |
tree | 75faf69e4ad765ea661fe245093cb93f36018550 | |
parent | d2b6c06274f37c5c6c967939ee556c4be5b568d0 (diff) |
Add documentation for newly added ASN1 functions
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15591)
-rw-r--r-- | doc/build.info | 18 | ||||
-rw-r--r-- | doc/man3/ASN1_EXTERN_FUNCS.pod | 181 | ||||
-rw-r--r-- | doc/man3/ASN1_aux_cb.pod | 284 | ||||
-rw-r--r-- | doc/man3/ASN1_item_d2i_bio.pod | 53 | ||||
-rw-r--r-- | doc/man3/ASN1_item_new.pod | 45 | ||||
-rw-r--r-- | doc/man3/X509_PUBKEY_new.pod | 15 | ||||
-rw-r--r-- | doc/man7/migration_guide.pod | 12 | ||||
-rw-r--r-- | include/openssl/asn1t.h.in | 2 | ||||
-rw-r--r-- | util/missingcrypto.txt | 4 | ||||
-rw-r--r-- | util/other.syms | 13 |
10 files changed, 609 insertions, 18 deletions
diff --git a/doc/build.info b/doc/build.info index b77dac210c..946cc24032 100644 --- a/doc/build.info +++ b/doc/build.info @@ -471,6 +471,10 @@ DEPEND[html/man3/ADMISSIONS.html]=man3/ADMISSIONS.pod GENERATE[html/man3/ADMISSIONS.html]=man3/ADMISSIONS.pod DEPEND[man/man3/ADMISSIONS.3]=man3/ADMISSIONS.pod GENERATE[man/man3/ADMISSIONS.3]=man3/ADMISSIONS.pod +DEPEND[html/man3/ASN1_EXTERN_FUNCS.html]=man3/ASN1_EXTERN_FUNCS.pod +GENERATE[html/man3/ASN1_EXTERN_FUNCS.html]=man3/ASN1_EXTERN_FUNCS.pod +DEPEND[man/man3/ASN1_EXTERN_FUNCS.3]=man3/ASN1_EXTERN_FUNCS.pod +GENERATE[man/man3/ASN1_EXTERN_FUNCS.3]=man3/ASN1_EXTERN_FUNCS.pod DEPEND[html/man3/ASN1_INTEGER_get_int64.html]=man3/ASN1_INTEGER_get_int64.pod GENERATE[html/man3/ASN1_INTEGER_get_int64.html]=man3/ASN1_INTEGER_get_int64.pod DEPEND[man/man3/ASN1_INTEGER_get_int64.3]=man3/ASN1_INTEGER_get_int64.pod @@ -511,6 +515,10 @@ DEPEND[html/man3/ASN1_TYPE_get.html]=man3/ASN1_TYPE_get.pod GENERATE[html/man3/ASN1_TYPE_get.html]=man3/ASN1_TYPE_get.pod DEPEND[man/man3/ASN1_TYPE_get.3]=man3/ASN1_TYPE_get.pod GENERATE[man/man3/ASN1_TYPE_get.3]=man3/ASN1_TYPE_get.pod +DEPEND[html/man3/ASN1_aux_cb.html]=man3/ASN1_aux_cb.pod +GENERATE[html/man3/ASN1_aux_cb.html]=man3/ASN1_aux_cb.pod +DEPEND[man/man3/ASN1_aux_cb.3]=man3/ASN1_aux_cb.pod +GENERATE[man/man3/ASN1_aux_cb.3]=man3/ASN1_aux_cb.pod DEPEND[html/man3/ASN1_generate_nconf.html]=man3/ASN1_generate_nconf.pod GENERATE[html/man3/ASN1_generate_nconf.html]=man3/ASN1_generate_nconf.pod DEPEND[man/man3/ASN1_generate_nconf.3]=man3/ASN1_generate_nconf.pod @@ -519,6 +527,10 @@ DEPEND[html/man3/ASN1_item_d2i_bio.html]=man3/ASN1_item_d2i_bio.pod GENERATE[html/man3/ASN1_item_d2i_bio.html]=man3/ASN1_item_d2i_bio.pod DEPEND[man/man3/ASN1_item_d2i_bio.3]=man3/ASN1_item_d2i_bio.pod GENERATE[man/man3/ASN1_item_d2i_bio.3]=man3/ASN1_item_d2i_bio.pod +DEPEND[html/man3/ASN1_item_new.html]=man3/ASN1_item_new.pod +GENERATE[html/man3/ASN1_item_new.html]=man3/ASN1_item_new.pod +DEPEND[man/man3/ASN1_item_new.3]=man3/ASN1_item_new.pod +GENERATE[man/man3/ASN1_item_new.3]=man3/ASN1_item_new.pod DEPEND[html/man3/ASN1_item_sign.html]=man3/ASN1_item_sign.pod GENERATE[html/man3/ASN1_item_sign.html]=man3/ASN1_item_sign.pod DEPEND[man/man3/ASN1_item_sign.3]=man3/ASN1_item_sign.pod @@ -2825,6 +2837,7 @@ DEPEND[man/man3/s2i_ASN1_IA5STRING.3]=man3/s2i_ASN1_IA5STRING.pod GENERATE[man/man3/s2i_ASN1_IA5STRING.3]=man3/s2i_ASN1_IA5STRING.pod IMAGEDOCS[man3]= HTMLDOCS[man3]=html/man3/ADMISSIONS.html \ +html/man3/ASN1_EXTERN_FUNCS.html \ html/man3/ASN1_INTEGER_get_int64.html \ html/man3/ASN1_INTEGER_new.html \ html/man3/ASN1_ITEM_lookup.html \ @@ -2835,8 +2848,10 @@ html/man3/ASN1_STRING_new.html \ html/man3/ASN1_STRING_print_ex.html \ html/man3/ASN1_TIME_set.html \ html/man3/ASN1_TYPE_get.html \ +html/man3/ASN1_aux_cb.html \ html/man3/ASN1_generate_nconf.html \ html/man3/ASN1_item_d2i_bio.html \ +html/man3/ASN1_item_new.html \ html/man3/ASN1_item_sign.html \ html/man3/ASYNC_WAIT_CTX_new.html \ html/man3/ASYNC_start_job.html \ @@ -3414,6 +3429,7 @@ html/man3/i2d_re_X509_tbs.html \ html/man3/o2i_SCT_LIST.html \ html/man3/s2i_ASN1_IA5STRING.html MANDOCS[man3]=man/man3/ADMISSIONS.3 \ +man/man3/ASN1_EXTERN_FUNCS.3 \ man/man3/ASN1_INTEGER_get_int64.3 \ man/man3/ASN1_INTEGER_new.3 \ man/man3/ASN1_ITEM_lookup.3 \ @@ -3424,8 +3440,10 @@ man/man3/ASN1_STRING_new.3 \ man/man3/ASN1_STRING_print_ex.3 \ man/man3/ASN1_TIME_set.3 \ man/man3/ASN1_TYPE_get.3 \ +man/man3/ASN1_aux_cb.3 \ man/man3/ASN1_generate_nconf.3 \ man/man3/ASN1_item_d2i_bio.3 \ +man/man3/ASN1_item_new.3 \ man/man3/ASN1_item_sign.3 \ man/man3/ASYNC_WAIT_CTX_new.3 \ man/man3/ASYNC_start_job.3 \ diff --git a/doc/man3/ASN1_EXTERN_FUNCS.pod b/doc/man3/ASN1_EXTERN_FUNCS.pod new file mode 100644 index 0000000000..800cc500ea --- /dev/null +++ b/doc/man3/ASN1_EXTERN_FUNCS.pod @@ -0,0 +1,181 @@ +=pod + +=head1 NAME + +ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func, +ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func, +IMPLEMENT_EXTERN_ASN1 +- ASN.1 external function support + +=head1 SYNOPSIS + + #include <openssl/asn1t.h> + + typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len, + const ASN1_ITEM *it, int tag, int aclass, char opt, + ASN1_TLC *ctx); + typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len, + const ASN1_ITEM *it, int tag, int aclass, char opt, + ASN1_TLC *ctx, OSSL_LIB_CTX *libctx, + const char *propq); + typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out, + const ASN1_ITEM *it, int tag, int aclass); + typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it); + typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it, + OSSL_LIB_CTX *libctx, const char *propq); + typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it); + typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval, + int indent, const char *fname, + const ASN1_PCTX *pctx); + + struct ASN1_EXTERN_FUNCS_st { + void *app_data; + ASN1_ex_new_func *asn1_ex_new; + ASN1_ex_free_func *asn1_ex_free; + ASN1_ex_free_func *asn1_ex_clear; + ASN1_ex_d2i *asn1_ex_d2i; + ASN1_ex_i2d *asn1_ex_i2d; + ASN1_ex_print_func *asn1_ex_print; + ASN1_ex_new_ex_func *asn1_ex_new_ex; + ASN1_ex_d2i_ex *asn1_ex_d2i_ex; + }; + typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS; + + #define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs) + +=head1 DESCRIPTION + +ASN.1 data structures templates are typically defined in OpenSSL using a series +of macros such as ASN1_SEQUENCE(), ASN1_SEQUENCE_END() and so on. Instead +templates can also be defined based entirely on external functions. These +external functions are called to perform operations such as creating a new +B<ASN1_VALUE> or converting an B<ASN1_VALUE> to or from DER encoding. + +The macro IMPLEMENT_EXTERN_ASN1() can be used to create such an externally +defined structure. The name of the structure should be supplied in the I<sname> +parameter. The tag for the structure (e.g. typically B<V_ASN1_SEQUENCE>) should +be supplied in the I<tag> parameter. Finally a pointer to an +B<ASN1_EXTERN_FUNCS> structure should be supplied in the I<fptrs> parameter. + +The B<ASN1_EXTERN_FUNCS> structure has the following entries. + +=over 4 + +=item I<app_data> + +A pointer to arbitrary application specific data. + +=item I<asn1_ex_new> + +A "new" function responsible for constructing a new B<ASN1_VALUE> object. The +newly constructed value should be stored in I<*pval>. The I<it> parameter is a +pointer to the B<ASN1_ITEM> template object created via the +IMPLEMENT_EXTERN_ASN1() macro. + +Returns a positive value on success or 0 on error. + +=item I<asn1_ex_free> + +A "free" function responsible for freeing the B<ASN1_VALUE> passed in I<*pval> +that was previously allocated via a "new" function. The I<it> parameter is a +pointer to the B<ASN1_ITEM> template object created via the +IMPLEMENT_EXTERN_ASN1() macro. + +=item I<asn1_ex_clear> + +A "clear" function responsible for clearing any data in the B<ASN1_VALUE> passed +in I<*pval> and making it suitable for reuse. The I<it> parameter is a pointer +to the B<ASN1_ITEM> template object created via the IMPLEMENT_EXTERN_ASN1() +macro. + +=item I<asn1_ex_d2i> + +A "d2i" function responsible for converting DER data with the tag I<tag> and +class I<class> into an B<ASN1_VALUE>. If I<*pval> is non-NULL then the +B<ASN_VALUE> it points to should be reused. Otherwise a new B<ASN1_VALUE> +should be allocated and stored in I<*pval>. I<*in> points to the DER data to be +decoded and I<len> is the length of that data. After decoding I<*in> should be +updated to point at the next byte after the decoded data. If the B<ASN1_VALUE> +is considered optional in this context then I<opt> will be nonzero. Otherwise +it will be zero. The I<it> parameter is a pointer to the B<ASN1_ITEM> template +object created via the IMPLEMENT_EXTERN_ASN1() macro. A pointer to the current +B<ASN1_TLC> context (which may be required for other ASN1 function calls) is +passed in the I<ctx> parameter. + +The I<asn1_ex_d2i> entry may be NULL if I<asn1_ex_d2i_ex> has been specified +instead. + +Returns <= 0 on error or a positive value on success. + +=item I<asn1_ex_i2d> + +An "i2d" function responsible for converting an B<ASN1_VALUE> into DER encoding. +On entry I<*pval> will contain the B<ASN1_VALUE> to be encoded. If default +tagging is to be used then I<tag> will be -1 on entry. Otherwise if implicit +tagging should be used then I<tag> and I<aclass> will be the tag and associated +class. + +If I<out> is not NULL then this function should write the DER encoded data to +the buffer in I<*out>, and then increment I<*out> to point to immediately after +the data just written. + +If I<out> is NULL then no data should be written but the length calculated and +returned as if it were. + +The I<asn1_ex_i2d> entry may be NULL if I<asn1_ex_i2d_ex> has been specified +instead. + +The return value should be negative if a fatal error occurred, or 0 if a +non-fatal error occurred. Otherwise it should return the length of the encoded +data. + +=item I<asn1_ex_print> + +A "print" function. I<out> is the BIO to print the output to. I<*pval> is the +B<ASN1_VALUE> to be printed. I<indent> is the number of spaces of indenting to +be printed before any data is printed. I<fname> is currently unused and is +always "". I<pctx> is a pointer to the B<ASN1_PCTX> for the print operation. + +Returns 0 on error or a positive value on success. If the return value is 2 then +an additional newline will be printed after the data printed by this function. + +=item I<asn1_ex_new_ex> + +This is the same as I<asn1_ex_new> except that it is additionally passed the +OSSL_LIB_CTX to be used in I<libctx> and any property query string to be used +for algorithm fetching in the I<propq> parameter. See +L<crypto(7)/ALGORITHM FETCHING> for further details. If I<asn1_ex_new_ex> is +non NULL, then it will always be called in preference to I<asn1_ex_new>. + +=item I<asn1_ex_d2i_ex> + +This is the same as I<asn1_ex_d2i> except that it is additionally passed the +OSSL_LIB_CTX to be used in I<libctx> and any property query string to be used +for algorithm fetching in the I<propq> parameter. See +L<crypto(7)/ALGORITHM FETCHING> for further details. If I<asn1_ex_d2i_ex> is +non NULL, then it will always be called in preference to I<asn1_ex_d2i>. + +=back + +=head1 RETURN VALUES + +Return values for the various callbacks are as described above. + +=head1 SEE ALSO + +L<ASN1_item_new_ex(3)> + +=head1 HISTORY + +The I<asn1_ex_new_ex> and I<asn1_ex_d2i_ex> callbacks were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/ASN1_aux_cb.pod b/doc/man3/ASN1_aux_cb.pod new file mode 100644 index 0000000000..12f7ddf82d --- /dev/null +++ b/doc/man3/ASN1_aux_cb.pod @@ -0,0 +1,284 @@ +=pod + +=head1 NAME + +ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb +- ASN.1 auxilliary data + +=head1 SYNOPSIS + + #include <openssl/asn1t.h> + + struct ASN1_AUX_st { + void *app_data; + int flags; + int ref_offset; /* Offset of reference value */ + int ref_lock; /* Offset to an CRYPTO_RWLOCK */ + ASN1_aux_cb *asn1_cb; + int enc_offset; /* Offset of ASN1_ENCODING structure */ + ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */ + }; + typedef struct ASN1_AUX_st ASN1_AUX; + + struct ASN1_PRINT_ARG_st { + BIO *out; + int indent; + const ASN1_PCTX *pctx; + }; + typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG; + + struct ASN1_STREAM_ARG_st { + BIO *out; + BIO *ndef_bio; + unsigned char **boundary; + }; + typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG; + + typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it, + void *exarg); + typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in, + const ASN1_ITEM *it, void *exarg); + +=head1 DESCRIPTION + +ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply +additional information about the ASN.1 structure. An B<ASN1_AUX> structure is +associated with the structure during the definition of the ASN.1 template. For +example an B<ASN1_AUX> structure will be associated by using one of the various +ASN.1 template definition macros that supply auxilliary information such as +ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(), +ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb(). + +An B<ASN1_AUX> structure contains the following information. + +=over 4 + +=item I<app_data> + +Arbitrary application data + +=item I<flags> + +Flags which indicate the auxiliarly functionality supported. + +The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting. + +The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the +object will be saved. + +The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the +sequence length value may not be correct. This should generally not be used. + +The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the +B<ASN1_AUX> callback should be used in preference to the non-const form. + +=item I<ref_offset> + +If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an +offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be +found for the purposes of reference counting. + +=item I<ref_lock> + +If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an +offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be +found for the purposes of reference counting. + +=item I<asn1_cb> + +A callback that will be invoked at various points during the processing of +the the B<ASN1_VALLUE>. See below for further details. + +=item I<enc_offset> + +Offset into the B<ASN1_VALUE> object where the original encoding of the object +will be saved if the B<ASN1_AFLG_ENCODING> flag has been set. + +=item I<asn1_const_cb> + +A callback that will be invoked at various points during the processing of +the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if +the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details. + +=back + +During the processing of an B<ASN1_VALUE> object the callbacks set via +I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events +indicated via the I<operation> parameter. The value of I<*in> will be the +B<ASN1_VALUE> object being processed based on the template in I<it>. An +additional operation specific parameter may be passed in I<exarg>. The currently +supported operations are as follows. The callbacks should return a positive +value on success or zero on error, unless otherwise noted below. + +=over 4 + +=item B<ASN1_OP_NEW_PRE> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the +B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2 +from the callback. On error it should return 0. + +=item B<ASN1_OP_NEW_POST> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +after an B<ASN1_VALUE> object has been allocated. The allocated object is in +I<*pval>. + +=item B<ASN1_OP_FREE_PRE> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately before an B<ASN1_VALUE> is freed. If the callback originally +constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at +this point and return 2 from the callback. Otherwise it should return 1 for +success or 0 on error. + +=item B<ASN1_OP_FREE_POST> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately after B<ASN1_VALUE> sub-structures are freed. + +=item B<ASN1_OP_D2I_PRE> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately before a "d2i" operation for the B<ASN1_VALUE>. + +=item B<ASN1_OP_D2I_POST> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately after a "d2i" operation for the B<ASN1_VALUE>. + +=item B<ASN1_OP_I2D_PRE> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately before a "i2d" operation for the B<ASN1_VALUE>. + +=item B<ASN1_OP_I2D_POST> + +Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure +immediately after a "i2d" operation for the B<ASN1_VALUE>. + +=item B<ASN1_OP_PRINT_PRE> + +Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately +before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an +B<ASN1_PRINT_ARG> structure (see below). + +=item B<ASN1_OP_PRINT_POST> + +Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately +after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an +B<ASN1_PRINT_ARG> structure (see below). + +=item B<ASN1_OP_STREAM_PRE> + +Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite +length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG> +structure (see below). + +=item B<ASN1_OP_STREAM_POST> + +Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite +length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG> +structure (see below). + +=item B<ASN1_OP_DETACHED_PRE> + +Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached" +value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a +B<ASN1_STREAM_ARG> structure (see below). + +=item B<ASN1_OP_DETACHED_POST> + +Invoked immediately after processing the B<ASN1_VALUE> data as a "detached" +value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a +B<ASN1_STREAM_ARG> structure (see below). + +=item B<ASN1_OP_DUP_PRE> + +Invoked immediate prior to an ASN1_VALUE being duplicated via a call to +ASN1_item_dup(). + +=item B<ASN1_OP_DUP_POST> + +Invoked immediate after to an ASN1_VALUE has been duplicated via a call to +ASN1_item_dup(). + +=item B<ASN1_OP_GET0_LIBCTX> + +Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE> +if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such +a value exists. + +=item B<ASN1_OP_GET0_PROPQ> + +Invoked in order to obtain the property query string associated with an +B<ASN1_VALUE> if any. A pointer to the property query string should be stored in +I<*exarg> if such a value exists. + +=back + +An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE> +and B<ASN1_OP_PRINT_POST> callback operations. It contains the following +information. + +=over 4 + +=item I<out> + +The B<BIO> being used to print the data out. + +=item I<ndef_bio> + +The current number of indent spaces that should be used for printing this data. + +=item I<pctx> + +The context for the B<ASN1_PCTX> operation. + +=back + +An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>, +B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST> +callback operations. It contains the following information. + +=over 4 + +=item I<out> + +The B<BIO> to stream through + +=item I<ndef_bio> + +The B<BIO> with filters appended + +=item I<boundary> + +The streaming I/O boundary. + +=back + +=head1 RETURN VALUES + +The callbacks return 0 on error and a positive value on success. Some operations +require specific positive success values as noted above. + +=head1 SEE ALSO + +L<ASN1_item_new_ex(3)> + +=head1 HISTORY + +The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and +B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/ASN1_item_d2i_bio.pod b/doc/man3/ASN1_item_d2i_bio.pod index bd3c9b06c2..9083f85f69 100644 --- a/doc/man3/ASN1_item_d2i_bio.pod +++ b/doc/man3/ASN1_item_d2i_bio.pod @@ -2,23 +2,65 @@ =head1 NAME -ASN1_item_d2i_bio, -ASN1_item_i2d_mem_bio +ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio, +ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio - decode and encode DER-encoded ASN.1 structures =head1 SYNOPSIS #include <openssl/asn1.h> + ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **val, const unsigned char **in, + long len, const ASN1_ITEM *it, + OSSL_LIB_CTX *libctx, const char *propq); + ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **val, const unsigned char **in, + long len, const ASN1_ITEM *it); + + void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *pval, + OSSL_LIB_CTX *libctx, const char *propq); void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *pval); + + void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x, + OSSL_LIB_CTX *libctx, const char *propq); + void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x); + BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val); =head1 DESCRIPTION -ASN1_item_d2i_bio() decodes the contents of its input BIO I<in>, +ASN1_item_d2i_ex() decodes the contents of the data stored in I<*in> of length +I<len> which must be a DER-encoded ASN.1 structure, using the ASN.1 template +I<it>. It places the result in I<*pval> unless I<pval> is NULL. If I<*pval> is +non-NULL on entry then the B<ASN1_VALUE> present there will be reused. Otherwise +a new B<ASN1_VALUE> will be allocated. If any algorithm fetches are required +during the process then they will use the B<OSSL_LIB_CTX>provided in the +I<libctx> parameter and the property query string in I<propq>. See +L<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching. +On exit I<*in> will be updated to point to the next byte in the buffer after the +decoded structure. + +ASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default +OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string. + +ASN1_item_d2i_bio_ex() decodes the contents of its input BIO I<in>, which must be a DER-encoded ASN.1 structure, using the ASN.1 template I<it> and places the result in I<*pval> unless I<pval> is NULL. -If I<in> is NULL it returns NULL, else a pointer to the parsed structure. +If I<in> is NULL it returns NULL, else a pointer to the parsed structure. If any +algorithm fetches are required during the process then they will use the +B<OSSL_LIB_CTX> provided in the I<libctx> parameter and the property query +string in I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for more information +about algorithm fetching. + +ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the +default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query +string. + +ASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE +pointer is provided instead of a BIO. + +ASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the +default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query +string. ASN1_item_i2d_mem_bio() encodes the given ASN.1 value I<val> using the ASN.1 template I<it> and returns the result in a memory BIO. @@ -31,7 +73,8 @@ ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error. =head1 HISTORY -ASN1_item_i2d_mem_bio() was added in OpenSSL 3.0. +The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex() +and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man3/ASN1_item_new.pod b/doc/man3/ASN1_item_new.pod new file mode 100644 index 0000000000..4a495604d4 --- /dev/null +++ b/doc/man3/ASN1_item_new.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +ASN1_item_new_ex, ASN1_item_new +- create new ASN.1 values + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + ASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx, + const char *propq); + ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it); + +=head1 DESCRIPTION + +ASN1_item_new_ex() creates a new B<ASN1_VALUE> structure based on the +B<ASN1_ITEM> template given in the I<it> parameter. If any algorithm fetches are +required during the process then they will use the B<OSSL_LIB_CTX> provided in +the I<libctx> parameter and the property query string in I<propq>. See +L<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching. + +ASN1_item_new() is the same as ASN1_item_new_ex() except that the default +B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query string. + +=head1 RETURN VALUES + +ASN1_item_new_ex() and ASN1_item_new() return a pointer to the newly created +B<ASN1_VALUE> or NULL on error. + +=head1 HISTORY + +The function ASN1_item_new_ex() was added in OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/X509_PUBKEY_new.pod b/doc/man3/X509_PUBKEY_new.pod index 059f2ac564..3d22857b80 100644 --- a/doc/man3/X509_PUBKEY_new.pod +++ b/doc/man3/X509_PUBKEY_new.pod @@ -2,7 +2,7 @@ =head1 NAME -X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup, +X509_PUBKEY_new_ex, X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup, X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get, d2i_PUBKEY_ex, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param, @@ -12,6 +12,7 @@ X509_PUBKEY_eq - SubjectPublicKeyInfo public key functions #include <openssl/x509.h> + X509_PUBKEY *X509_PUBKEY_new_ex(OSSL_LIB_CTX *libctx, const char *propq); X509_PUBKEY *X509_PUBKEY_new(void); void X509_PUBKEY_free(X509_PUBKEY *a); X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a); @@ -44,7 +45,14 @@ X509_PUBKEY_eq - SubjectPublicKeyInfo public key functions The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo> structure defined in RFC5280 and used in certificates and certificate requests. -X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure. +X509_PUBKEY_new_ex() allocates and initializes an B<X509_PUBKEY> structure +associated with the given B<OSSL_LIB_CTX> in the I<libctx> parameter. Any +algorithm fetches associated with using the B<X509_PUBKEY> object will use +the property query string I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for +further information about algorithm fetching. + +X509_PUBKEY_new() is the same as X509_PUBKEY_new_ex() except that the default +(NULL) B<OSSL_LIB_CTX> and a NULL property query string are used. X509_PUBKEY_dup() creates a duplicate copy of the B<X509_PUBKEY> object specified by I<a>. @@ -127,7 +135,8 @@ L<X509_get_pubkey(3)>, =head1 HISTORY -The X509_PUBKEY_eq() function was added in OpenSSL 3.0. +The X509_PUBKEY_new_ex() and X509_PUBKEY_eq() functions were added in OpenSSL +3.0. =head1 COPYRIGHT diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod index e2d21a9540..6a71d68b9a 100644 --- a/doc/man7/migration_guide.pod +++ b/doc/man7/migration_guide.pod @@ -562,10 +562,11 @@ B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call t L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>. Some functions can be passed an object that has already been set up with a library -context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)> and L<d2i_X509_REQ(3)>. -If NULL is passed instead then the created object will be set up with the -default library context. Use L<X509_new_ex(3)>, L<X509_CRL_new_ex(3)> and -L<X509_REQ_new_ex(3)> if a library context is required. +context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and +L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be +set up with the default library context. Use L<X509_new_ex(3)>, +L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a +library context is required. All functions listed below with a I<NAME> have a replacment function I<NAME_ex> that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other @@ -575,7 +576,8 @@ mappings are listed along with the respective name. =item - -L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)> +L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>, +L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)> =item - diff --git a/include/openssl/asn1t.h.in b/include/openssl/asn1t.h.in index 321f106e03..2e47473327 100644 --- a/include/openssl/asn1t.h.in +++ b/include/openssl/asn1t.h.in @@ -704,7 +704,7 @@ typedef struct ASN1_AUX_st { void *app_data; int flags; int ref_offset; /* Offset of reference value */ - int ref_lock; /* Lock type to use */ + int ref_lock; /* Offset of lock value */ ASN1_aux_cb *asn1_cb; int enc_offset; /* Offset of ASN1_ENCODING structure */ ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */ diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index cd81ba7e09..67bfc7859d 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -137,9 +137,6 @@ ASN1_dup(3) ASN1_get_object(3) ASN1_i2d_bio(3) ASN1_i2d_fp(3) -ASN1_item_d2i(3) -ASN1_item_d2i_bio(3) -ASN1_item_d2i_fp(3) ASN1_item_digest(3) ASN1_item_dup(3) ASN1_item_ex_d2i(3) @@ -151,7 +148,6 @@ ASN1_item_i2d(3) ASN1_item_i2d_bio(3) ASN1_item_i2d_fp(3) ASN1_item_ndef_i2d(3) -ASN1_item_new(3) ASN1_item_pack(3) ASN1_item_print(3) ASN1_item_unpack(3) diff --git a/util/other.syms b/util/other.syms index 05c70df44f..8e1824c220 100644 --- a/util/other.syms +++ b/util/other.syms @@ -11,7 +11,20 @@ OPENSSL_instrument_bus2 assembler # ADMISSION_SYNTAX datatype ADMISSIONS datatype +ASN1_AUX datatype +ASN1_aux_cb datatype +ASN1_aux_const_cb datatype +ASN1_ex_d2i datatype +ASN1_ex_d2i_ex datatype +ASN1_ex_free_func datatype +ASN1_ex_i2d datatype +ASN1_ex_new_func datatype +ASN1_ex_new_ex_func datatype +ASN1_ex_print_func datatype +ASN1_EXTERN_FUNCS datatype ASN1_ITEM datatype +ASN1_PRINT_ARG datatype +ASN1_STREAM_ARG datatype ASN1_STRING_TABLE datatype ASYNC_callback_fn datatype BIO_ADDR datatype |