[openssl] OpenSSL_1_1_1-stable update

[dev at ddvo.net]

The branch OpenSSL_1_1_1-stable has been updated
       via  4623700d4eaaa250b49032768be2e97a147f3a1e (commit)
      from  e5050aa1bbce84e359bfd35de60dd745627e8d41 (commit)


- Log -----------------------------------------------------------------
commit 4623700d4eaaa250b49032768be2e97a147f3a1e
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Fri Dec 3 15:18:07 2021 +0100

    OBJ_obj2txt(): fix off-by-one documentation of the result
    
    This backports the doc improvements of #17188.
    
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    
    (cherry picked from commit e36d10925396b6519e1abd338e1ef62cd5b1c9e6)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OBJ_nid2obj.pod | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod
index 74379ad817..81e57154f1 100644
--- a/doc/man3/OBJ_nid2obj.pod
+++ b/doc/man3/OBJ_nid2obj.pod
@@ -68,13 +68,15 @@ 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
-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
-form will always be used.
+OBJ_obj2txt() converts the B<ASN1_OBJECT> I<a> into a textual representation.
+Unless I<buf> is NULL,
+the representation is written as a NUL-terminated string to I<buf>, where
+at most I<buf_len> bytes are written, truncating the result if necessary.
+In any case it returns the total string length, excluding the NUL character,
+required for non-truncated representation, or -1 on error.
+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 I<no_name> is 1 then the numerical form will always be used.
 
 i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I<no_name> set to zero.
 
@@ -141,6 +143,13 @@ 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.
+
+i2t_ASN1_OBJECT() an OBJ_obj2txt() return -1 on error.
+On success, they return the length of the string written to I<buf> if I<buf> is
+not NULL and I<buf_len> is big enough, otherwise the total string length.
+Note that this does not count the trailing NUL character.
+
 =head1 EXAMPLES
 
 Create an object for B<commonName>:
@@ -161,15 +170,6 @@ Create a new object directly:
 
  obj = OBJ_txt2obj("1.2.3.4", 1);
 
-=head1 BUGS
-
-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
-be set to a positive value. A buffer length of 80 should be more
-than enough to handle any OID encountered in practice.
-
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>