Update documentation

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3301)

1 files changed, 32 insertions, 1 deletions

diff --git a/doc/man3/X509_get0_signature.pod b/doc/man3/X509_get0_signature.pod
index 61a2dda981..f63c5a5b68 100644
--- a/doc/man3/X509_get0_signature.pod
+++ b/doc/man3/X509_get0_signature.pod
@@ -4,7 +4,8 @@
 
 X509_get0_signature, X509_get_signature_nid, X509_get0_tbs_sigalg,
 X509_REQ_get0_signature, X509_REQ_get_signature_nid, X509_CRL_get0_signature,
-X509_CRL_get_signature_nid - signature information
+X509_CRL_get_signature_nid, X509_get_signature_info, X509_SIG_INFO_get,
+X509_SIG_INFO_set - signature information
 
 =head1 SYNOPSIS
 
@@ -26,6 +27,14 @@ X509_CRL_get_signature_nid - signature information
                               const X509_ALGOR **palg);
  int X509_CRL_get_signature_nid(const X509_CRL *crl);
 
+ int X509_get_signature_info(X509 *x, int *mdnid, int *pknid, int *secbits,
+                             uint32_t *flags);
+
+ int X509_SIG_INFO_get(const X509_SIG_INFO *siginf, int *mdnid, int *pknid,
+                      int *secbits, uint32_t *flags);
+ void X509_SIG_INFO_set(X509_SIG_INFO *siginf, int mdnid, int pknid,
+                        int secbits, uint32_t flags);
+
 =head1 DESCRIPTION
 
 X509_get0_signature() sets B<*psig> to the signature of B<x> and B<*palg>
@@ -42,6 +51,18 @@ X509_REQ_get0_signature(), X509_REQ_get_signature_nid()
 X509_CRL_get0_signature() and X509_CRL_get_signature_nid() perform the
 same function for certificate requests and CRLs.
 
+X509_get_signature_info() retrieves information about the signature of
+certificate B<x>. The NID of the signing digest is written to B<*mdnid>,
+the public key algorithm to B<*pknid>, the effective security bits to
+B<*secbits> and flag details to B<*flags>. Any of the parameters can
+be set to B<NULL> if the information is not required.
+
+X509_SIG_INFO_get() and X509_SIG_INFO_set() get and set information
+about a signature in an B<X509_SIG_INFO> structure. They are only
+used by implementations of algorithms which need to set custom
+signature information: most applications will never need to call
+them.
+
 =head1 NOTES
 
 These functions provide lower level access to signatures in certificates
@@ -49,6 +70,12 @@ where an application wishes to analyse or generate a signature in a form
 where X509_sign() et al is not appropriate (for example a non standard
 or unsupported format).
 
+The security bits returned by X509_get_signature_info() refers to information
+available from the certificate signature (such as the signing digest). In some
+cases the actual security of the signature is less because the signing
+key is less secure: for example a certificate signed using SHA-512 and a
+1024 bit RSA key.
+
 =head1 RETURN VALUES
 
 X509_get_signature_nid(), X509_REQ_get_signature_nid() and
@@ -57,6 +84,10 @@ X509_CRL_get_signature_nid() return a NID.
 X509_get0_signature(), X509_REQ_get0_signature() and
 X509_CRL_get0_signature() do not return values.
 
+X509_get_signature_info() returns 1 if the signature information
+returned is valid or 0 if the information is not available (e.g.
+unknown algorithms or malformed parameters).
+
 =head1 SEE ALSO
 
 L<d2i_X509(3)>,