From 3d9d1ce52904660757dadeb629926932abe25158 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 1 Jun 2021 15:17:38 +0100 Subject: [PATCH] Add documentation for newly added ASN1 functions Reviewed-by: Shane Lontis Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/15591) --- doc/build.info | 18 +++ doc/man3/ASN1_EXTERN_FUNCS.pod | 181 +++++++++++++++++++++ doc/man3/ASN1_aux_cb.pod | 284 +++++++++++++++++++++++++++++++++ doc/man3/ASN1_item_d2i_bio.pod | 53 +++++- doc/man3/ASN1_item_new.pod | 45 ++++++ doc/man3/X509_PUBKEY_new.pod | 15 +- doc/man7/migration_guide.pod | 12 +- include/openssl/asn1t.h.in | 2 +- util/missingcrypto.txt | 4 - util/other.syms | 13 ++ 10 files changed, 609 insertions(+), 18 deletions(-) create mode 100644 doc/man3/ASN1_EXTERN_FUNCS.pod create mode 100644 doc/man3/ASN1_aux_cb.pod create mode 100644 doc/man3/ASN1_item_new.pod 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 + + 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 or converting an B 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 +parameter. The tag for the structure (e.g. typically B) should +be supplied in the I parameter. Finally a pointer to an +B structure should be supplied in the I parameter. + +The B structure has the following entries. + +=over 4 + +=item I + +A pointer to arbitrary application specific data. + +=item I + +A "new" function responsible for constructing a new B object. The +newly constructed value should be stored in I<*pval>. The I parameter is a +pointer to the B template object created via the +IMPLEMENT_EXTERN_ASN1() macro. + +Returns a positive value on success or 0 on error. + +=item I + +A "free" function responsible for freeing the B passed in I<*pval> +that was previously allocated via a "new" function. The I parameter is a +pointer to the B template object created via the +IMPLEMENT_EXTERN_ASN1() macro. + +=item I + +A "clear" function responsible for clearing any data in the B passed +in I<*pval> and making it suitable for reuse. The I parameter is a pointer +to the B template object created via the IMPLEMENT_EXTERN_ASN1() +macro. + +=item I + +A "d2i" function responsible for converting DER data with the tag I and +class I into an B. If I<*pval> is non-NULL then the +B it points to should be reused. Otherwise a new B +should be allocated and stored in I<*pval>. I<*in> points to the DER data to be +decoded and I 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 +is considered optional in this context then I will be nonzero. Otherwise +it will be zero. The I parameter is a pointer to the B template +object created via the IMPLEMENT_EXTERN_ASN1() macro. A pointer to the current +B context (which may be required for other ASN1 function calls) is +passed in the I parameter. + +The I entry may be NULL if I has been specified +instead. + +Returns <= 0 on error or a positive value on success. + +=item I + +An "i2d" function responsible for converting an B into DER encoding. +On entry I<*pval> will contain the B to be encoded. If default +tagging is to be used then I will be -1 on entry. Otherwise if implicit +tagging should be used then I and I will be the tag and associated +class. + +If I 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 is NULL then no data should be written but the length calculated and +returned as if it were. + +The I entry may be NULL if I 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 + +A "print" function. I is the BIO to print the output to. I<*pval> is the +B to be printed. I is the number of spaces of indenting to +be printed before any data is printed. I is currently unused and is +always "". I is a pointer to the B 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 + +This is the same as I except that it is additionally passed the +OSSL_LIB_CTX to be used in I and any property query string to be used +for algorithm fetching in the I parameter. See +L for further details. If I is +non NULL, then it will always be called in preference to I. + +=item I + +This is the same as I except that it is additionally passed the +OSSL_LIB_CTX to be used in I and any property query string to be used +for algorithm fetching in the I parameter. See +L for further details. If I is +non NULL, then it will always be called in preference to I. + +=back + +=head1 RETURN VALUES + +Return values for the various callbacks are as described above. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The I and I 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. + +=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 + + 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 object to supply +additional information about the ASN.1 structure. An B structure is +associated with the structure during the definition of the ASN.1 template. For +example an B 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 structure contains the following information. + +=over 4 + +=item I + +Arbitrary application data + +=item I + +Flags which indicate the auxiliarly functionality supported. + +The B flag indicates that objects support reference counting. + +The B flag indicates that the original encoding of the +object will be saved. + +The B 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 flag indicates that the "const" form of the +B callback should be used in preference to the non-const form. + +=item I + +If the B flag is set then this value is assumed to be an +offset into the B structure where a B may be +found for the purposes of reference counting. + +=item I + +If the B flag is set then this value is assumed to be an +offset into the B structure where a B may be +found for the purposes of reference counting. + +=item I + +A callback that will be invoked at various points during the processing of +the the B. See below for further details. + +=item I + +Offset into the B object where the original encoding of the object +will be saved if the B flag has been set. + +=item I + +A callback that will be invoked at various points during the processing of +the the B. This is used in preference to the I callback if +the B flag is set. See below for further details. + +=back + +During the processing of an B object the callbacks set via +I or I will be invoked as a result of various events +indicated via the I parameter. The value of I<*in> will be the +B object being processed based on the template in I. An +additional operation specific parameter may be passed in I. 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 + +Invoked when processing a B, B or B structure +prior to an B object being allocated. The callback may allocate the +B 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 + +Invoked when processing a B, B or B structure +after an B object has been allocated. The allocated object is in +I<*pval>. + +=item B + +Invoked when processing a B, B or B structure +immediately before an B is freed. If the callback originally +constructed the B via B 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 + +Invoked when processing a B, B or B structure +immediately after B sub-structures are freed. + +=item B + +Invoked when processing a B, B or B structure +immediately before a "d2i" operation for the B. + +=item B + +Invoked when processing a B, B or B structure +immediately after a "d2i" operation for the B. + +=item B + +Invoked when processing a B, B or B structure +immediately before a "i2d" operation for the B. + +=item B + +Invoked when processing a B, B or B structure +immediately after a "i2d" operation for the B. + +=item B + +Invoked when processing a B or B structure immediately +before printing the B. The I argument will be a pointer to an +B structure (see below). + +=item B + +Invoked when processing a B or B structure immediately +after printing the B. The I argument will be a pointer to an +B structure (see below). + +=item B + +Invoked immediately prior to streaming the B data using indefinite +length encoding. The I argument will be a pointer to a B +structure (see below). + +=item B + +Invoked immediately after streaming the B data using indefinite +length encoding. The I argument will be a pointer to a B +structure (see below). + +=item B + +Invoked immediately prior to processing the B data as a "detached" +value (as used in CMS and PKCS7). The I argument will be a pointer to a +B structure (see below). + +=item B + +Invoked immediately after processing the B data as a "detached" +value (as used in CMS and PKCS7). The I argument will be a pointer to a +B structure (see below). + +=item B + +Invoked immediate prior to an ASN1_VALUE being duplicated via a call to +ASN1_item_dup(). + +=item B + +Invoked immediate after to an ASN1_VALUE has been duplicated via a call to +ASN1_item_dup(). + +=item B + +Invoked in order to obtain the B associated with an B +if any. A pointer to an B should be stored in I<*exarg> if such +a value exists. + +=item B + +Invoked in order to obtain the property query string associated with an +B if any. A pointer to the property query string should be stored in +I<*exarg> if such a value exists. + +=back + +An B object is used during processing of B +and B callback operations. It contains the following +information. + +=over 4 + +=item I + +The B being used to print the data out. + +=item I + +The current number of indent spaces that should be used for printing this data. + +=item I + +The context for the B operation. + +=back + +An B object is used during processing of B, +B, B and B +callback operations. It contains the following information. + +=over 4 + +=item I + +The B to stream through + +=item I + +The B with filters appended + +=item I + +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 + +=head1 HISTORY + +The ASN1_aux_const_cb() callback and the B and +B 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. + +=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 + 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, +ASN1_item_d2i_ex() decodes the contents of the data stored in I<*in> of length +I which must be a DER-encoded ASN.1 structure, using the ASN.1 template +I. It places the result in I<*pval> unless I is NULL. If I<*pval> is +non-NULL on entry then the B present there will be reused. Otherwise +a new B will be allocated. If any algorithm fetches are required +during the process then they will use the Bprovided in the +I parameter and the property query string in I. See +L 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, which must be a DER-encoded ASN.1 structure, using the ASN.1 template I and places the result in I<*pval> unless I is NULL. -If I is NULL it returns NULL, else a pointer to the parsed structure. +If I 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 provided in the I parameter and the property query +string in I. See L for more information +about algorithm fetching. + +ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the +default B 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 is used (i.e. NULL) and with a NULL property query +string. ASN1_item_i2d_mem_bio() encodes the given ASN.1 value I using the ASN.1 template I 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 + + 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 structure based on the +B template given in the I parameter. If any algorithm fetches are +required during the process then they will use the B provided in +the I parameter and the property query string in I. See +L for more information about algorithm fetching. + +ASN1_item_new() is the same as ASN1_item_new_ex() except that the default +B 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 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. + +=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 + 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 structure represents the ASN.1 B structure defined in RFC5280 and used in certificates and certificate requests. -X509_PUBKEY_new() allocates and initializes an B structure. +X509_PUBKEY_new_ex() allocates and initializes an B structure +associated with the given B in the I parameter. Any +algorithm fetches associated with using the B object will use +the property query string I. See L for +further information about algorithm fetching. + +X509_PUBKEY_new() is the same as X509_PUBKEY_new_ex() except that the default +(NULL) B and a NULL property query string are used. X509_PUBKEY_dup() creates a duplicate copy of the B object specified by I. @@ -127,7 +135,8 @@ L, =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 such as EVP_aes_128_cbc() should be replaced vith a call t L. See L. Some functions can be passed an object that has already been set up with a library -context such as L, L and L. -If NULL is passed instead then the created object will be set up with the -default library context. Use L, L and -L if a library context is required. +context such as L, L, L and +L. If NULL is passed instead then the created object will be +set up with the default library context. Use L, +L, L and L if a +library context is required. All functions listed below with a I have a replacment function I that takes B as an additional argument. Functions that have other @@ -575,7 +576,8 @@ mappings are listed along with the respective name. =item - -L and L +L, L, L, +L, L and L =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