From 599429e09a6ddae2d6de2e031bf82817f29f4af0 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 9 Jun 2021 16:10:03 +0100 Subject: [PATCH] Add documentation for the newly added OBJ up calls Reviewed-by: Richard Levitte Reviewed-by: Tim Hudson Reviewed-by: Tomas Mraz Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/15681) --- doc/man3/OBJ_nid2obj.pod | 51 +++++++++++++++++++++++--------------- doc/man7/provider-base.pod | 34 ++++++++++++++++++++++--- util/missingcrypto.txt | 1 - 3 files changed, 62 insertions(+), 24 deletions(-) diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod index 9089f95622..54b751f6df 100644 --- a/doc/man3/OBJ_nid2obj.pod +++ b/doc/man3/OBJ_nid2obj.pod @@ -5,7 +5,7 @@ i2t_ASN1_OBJECT, OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, -OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup +OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup, OBJ_add_sigid - ASN1 object utility functions =head1 SYNOPSIS @@ -35,6 +35,8 @@ OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup size_t OBJ_length(const ASN1_OBJECT *obj); const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); + int OBJ_add_sigid(int signid, int dig_id, int pkey_id); + Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining B with a suitable version value, see L: @@ -52,46 +54,53 @@ are available as defined constants. For the functions below, application code should treat all returned values -- OIDs, NIDs, or names -- as constants. -OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B to +OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID I to an ASN1_OBJECT structure, its long name and its short name respectively, or B if an error occurred. OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID -for the object B, the long name or the short name respectively +for the object I, the long name I or the short name I respectively or NID_undef if an error occurred. -OBJ_txt2nid() returns NID corresponding to text string . B can be +OBJ_txt2nid() returns NID corresponding to text string I. I can be a long name, a short name or the numerical representation of an object. -OBJ_txt2obj() converts the text string B into an ASN1_OBJECT structure. -If B is 0 then long names and short names will be interpreted -as well as numerical forms. If B is 1 only the numerical form +OBJ_txt2obj() converts the text string I into an ASN1_OBJECT structure. +If I is 0 then long names and short names will be interpreted +as well as numerical forms. If I is 1 only the numerical form is acceptable. -OBJ_obj2txt() converts the B B into a textual representation. -The representation is written as a null terminated string to B -at most B bytes are written, truncating the result if necessary. -The total amount of space required is returned. If B is 0 then +OBJ_obj2txt() converts the B I into a textual representation. +The representation is written as a null terminated string to I +at most I bytes are written, truncating the result if necessary. +The total amount of space required is returned. If I is 0 then if the object has a long or short name then that will be used, otherwise -the numerical form will be used. If B is 1 then the numerical +the numerical form will be used. If I is 1 then the numerical form will always be used. -i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B set to zero. +i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I set to zero. -OBJ_cmp() compares B to B. If the two are identical 0 is returned. +OBJ_cmp() compares I to I. If the two are identical 0 is returned. -OBJ_dup() returns a copy of B. +OBJ_dup() returns a copy of I. -OBJ_create() adds a new object to the internal table. B is the -numerical form of the object, B the short name and B the +OBJ_create() adds a new object to the internal table. I is the +numerical form of the object, I the short name and I the long name. A new NID is returned for the created object in case of success and NID_undef in case of failure. -OBJ_length() returns the size of the content octets of B. +OBJ_length() returns the size of the content octets of I. -OBJ_get0_data() returns a pointer to the content octets of B. +OBJ_get0_data() returns a pointer to the content octets of I. The returned pointer is an internal pointer which B be freed. +OBJ_add_sigid() creates a new composite "Signature Algorithm" that associates a +given NID with two other NIDs - one representing the underlying signature +algorithm and the other representing a digest algorithm to be used in +conjunction with it. I represents the NID for the composite "Signature +Algorithm", I is the NID for the digest algorithm and I is the +NID for the underlying signature algorithm. + OBJ_cleanup() releases any resources allocated by creating new objects. =head1 NOTES @@ -141,6 +150,8 @@ on error. OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or B on error. +OBJ_add_sigid() returns 1 on success or 0 on error. + =head1 EXAMPLES Create an object for B: @@ -166,7 +177,7 @@ Create a new object directly: OBJ_obj2txt() is awkward and messy to use: it doesn't follow the convention of other OpenSSL functions where the buffer can be set to B to determine the amount of data that should be written. -Instead B must point to a valid buffer and B should +Instead I must point to a valid buffer and I should be set to a positive value. A buffer length of 80 should be more than enough to handle any OID encountered in practice. diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index 7ade4a1c8e..0eb2f5d243 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -31,6 +31,11 @@ provider-base void core_vset_error(const OSSL_CORE_HANDLE *handle, uint32_t reason, const char *fmt, va_list args); + int core_obj_add_sigid(const OSSL_CORE_HANDLE *prov, const char *sign_name, + const char *digest_name, const char *pkey_name); + int core_obj_create(const OSSL_CORE_HANDLE *handle, const char *oid, + const char *sn, const char *ln); + /* * Some OpenSSL functionality is directly offered to providers via * dispatch @@ -144,6 +149,8 @@ provider): core_new_error OSSL_FUNC_CORE_NEW_ERROR core_set_error_debug OSSL_FUNC_CORE_SET_ERROR_DEBUG core_vset_error OSSL_FUNC_CORE_VSET_ERROR + core_obj_add_sigid OSSL_FUNC_CORE_OBJ_ADD_SIGID + core_obj_create OSSL_FUNC_CORE_OBJ_CREATE CRYPTO_malloc OSSL_FUNC_CRYPTO_MALLOC CRYPTO_zalloc OSSL_FUNC_CRYPTO_ZALLOC CRYPTO_memdup OSSL_FUNC_CRYPTO_MEMDUP @@ -250,16 +257,37 @@ This corresponds to the OpenSSL function L. =back +The core_obj_create() function registers a new OID and associated short name +I and long name I for the given I. It is similar to the OpenSSL +function L except that it returns 1 on success or 0 on failure. +It will treat as success the case where the OID already exists (even if the +short name I or long name I provided as arguments differ from those +associated with the existing OID, in which case the new names are not +associated). + +The core_obj_add_sigid() function registers a new composite signature algorithm +(I) consisting of an underlying signature algorithm (I) +and digest algorithm (I) for the given I. It assumes that +the OIDs for the composite signature algorithm as well as for the underlying +signature and digest algorithms are either already known to OpenSSL or have been +registered via a call to core_obj_create(). It corresponds to the OpenSSL +function L, except that the objects are identified by name +rather than a numeric NID. Any name (OID, short name or long name) can be used +to identify the object. It will treat as success the case where the composite +signature algorithm already exists (even if registered against a different +underlying signature or digest algorithm). It returns 1 on success or 0 on +failure. + CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_memdup(), CRYPTO_strdup(), CRYPTO_strndup(), CRYPTO_free(), CRYPTO_clear_free(), CRYPTO_realloc(), CRYPTO_clear_realloc(), CRYPTO_secure_malloc(), CRYPTO_secure_zalloc(), CRYPTO_secure_free(), CRYPTO_secure_clear_free(), CRYPTO_secure_allocated(), BIO_new_file(), BIO_new_mem_buf(), BIO_read_ex(), BIO_write_ex(), BIO_up_ref(), -BIO_free(), BIO_vprintf(), BIO_vsnprintf(), OPENSSL_cleanse() -and OPENSSL_hexstr2buf() correspond exactly to the public functions with +BIO_free(), BIO_vprintf(), BIO_vsnprintf(), OPENSSL_cleanse() and +OPENSSL_hexstr2buf() correspond exactly to the public functions with the same name. As a matter of fact, the pointers in the B -array are direct pointers to those public functions. Note that the BIO +array are typically direct pointers to those public functions. Note that the BIO functions take an B type rather than the standard B type. This is to ensure that a provider does not mix BIOs from the core with BIOs used on the provider side (the two are not compatible). diff --git a/util/missingcrypto.txt b/util/missingcrypto.txt index 67bfc7859d..f01b47162d 100644 --- a/util/missingcrypto.txt +++ b/util/missingcrypto.txt @@ -729,7 +729,6 @@ OBJ_NAME_init(3) OBJ_NAME_new_index(3) OBJ_NAME_remove(3) OBJ_add_object(3) -OBJ_add_sigid(3) OBJ_bsearch_(3) OBJ_bsearch_ex_(3) OBJ_create_objects(3)