Add documentation for the newly added OBJ up calls

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15681)

2 files changed, 62 insertions, 23 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<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
@@ -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<n> to
+OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID I<n> to
 an ASN1_OBJECT structure, its long name and its short name respectively,
 or B<NULL> if an error occurred.
 
 OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
-for the object B<o>, the long name <ln> or the short name <sn> respectively
+for the object I<o>, the long name I<ln> or the short name I<sn> respectively
 or NID_undef if an error occurred.
 
-OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
+OBJ_txt2nid() returns NID corresponding to text string I<s>. I<s> can be
 a long name, a short name or the numerical representation of an object.
 
-OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
-If B<no_name> is 0 then long names and short names will be interpreted
-as well as numerical forms. If B<no_name> is 1 only the numerical form
+OBJ_txt2obj() converts the text string I<s> into an ASN1_OBJECT structure.
+If I<no_name> is 0 then long names and short names will be interpreted
+as well as numerical forms. If I<no_name> is 1 only the numerical form
 is acceptable.
 
-OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
-The representation is written as a null terminated string to B<buf>
-at most B<buf_len> bytes are written, truncating the result if necessary.
-The total amount of space required is returned. If B<no_name> is 0 then
+OBJ_obj2txt() converts the B<ASN1_OBJECT> I<a> into a textual representation.
+The representation is written as a null terminated string to I<buf>
+at most I<buf_len> bytes are written, truncating the result if necessary.
+The total amount of space required is returned. If I<no_name> 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<no_name> is 1 then the numerical
+the numerical form will be used. If I<no_name> is 1 then the numerical
 form will always be used.
 
-i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero.
+i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I<no_name> set to zero.
 
-OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
+OBJ_cmp() compares I<a> to I<b>. If the two are identical 0 is returned.
 
-OBJ_dup() returns a copy of B<o>.
+OBJ_dup() returns a copy of I<o>.
 
-OBJ_create() adds a new object to the internal table. B<oid> is the
-numerical form of the object, B<sn> the short name and B<ln> the
+OBJ_create() adds a new object to the internal table. I<oid> is the
+numerical form of the object, I<sn> the short name and I<ln> 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>.
+OBJ_length() returns the size of the content octets of I<obj>.
 
-OBJ_get0_data() returns a pointer to the content octets of B<obj>.
+OBJ_get0_data() returns a pointer to the content octets of I<obj>.
 The returned pointer is an internal pointer which B<must not> 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<signid> represents the NID for the composite "Signature
+Algorithm", I<dig_id> is the NID for the digest algorithm and I<pkey_id> 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<NID_undef> on error.
 
+OBJ_add_sigid() returns 1 on success or 0 on error.
+
 =head1 EXAMPLES
 
 Create an object for B<commonName>:
@@ -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<NULL> to determine the amount of data that should be written.
-Instead B<buf> must point to a valid buffer and B<buf_len> should
+Instead I<buf> must point to a valid buffer and I<buf_len> 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<ERR_vset_error(3)>.
 
 =back
 
+The core_obj_create() function registers a new OID and associated short name
+I<sn> and long name I<ln> for the given I<handle>. It is similar to the OpenSSL
+function L<OBJ_create(3)> 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<sn> or long name I<ln> 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<sign_name>) consisting of an underlying signature algorithm (I<pkey_name>)
+and digest algorithm (I<digest_name>) for the given I<handle>. 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<OBJ_add_sigid(3)>, 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<OSSL_DISPATCH>
-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<OSSL_CORE_BIO> type rather than the standard B<BIO>
 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).