Document X509_get0_signature_info()

Loosely based on the OpenSSL 1.1 documentation but extended quite a bit to
explain what the flags mean and what info they do (and do not) convey. With
the usual valuable feedback from jmc.

ok jmc

diff --git a/lib/libcrypto/man/X509_get0_signature.3 b/lib/libcrypto/man/X509_get0_signature.3
index f3ad398..dc3be2c 100644 (file)
--- a/lib/libcrypto/man/X509_get0_signature.3
+++ b/lib/libcrypto/man/X509_get0_signature.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_get0_signature.3,v 1.8 2023/03/16 12:01:47 job Exp $
+.\" $OpenBSD: X509_get0_signature.3,v 1.9 2024/08/28 07:18:55 tb Exp $
 .\" selective merge up to:
 .\" OpenSSL man3/X509_get0_signature 2f7a2520 Apr 25 17:28:08 2017 +0100
 .\"
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 16 2023 $
+.Dd $Mdocdate: August 28 2024 $
 .Dt X509_GET0_SIGNATURE 3
 .Os
 .Sh NAME
@@ -78,7 +78,8 @@
 .Nm X509_get_signature_type ,
 .Nm X509_get_signature_nid ,
 .Nm X509_REQ_get_signature_nid ,
-.Nm X509_CRL_get_signature_nid
+.Nm X509_CRL_get_signature_nid ,
+.Nm X509_get_signature_info
 .Nd signature information
 .Sh SYNOPSIS
 .In openssl/x509.h
@@ -124,6 +125,14 @@
 .Fo X509_CRL_get_signature_nid
 .Fa "const X509_CRL *crl"
 .Fc
+.Ft int
+.Fo X509_get_signature_info
+.Fa "X509 *x"
+.Fa "int *md_nid"
+.Fa "int *pkey_nid"
+.Fa "int *security_bits"
+.Fa "uint32_t *flags"
+.Fc
 .Sh DESCRIPTION
 .Fn X509_get0_signature ,
 .Fn X509_REQ_get0_signature ,
@@ -170,6 +179,51 @@ respectively, just like
 .Xr EVP_PKEY_id 3
 does.
 .Pp
+.Fn X509_get_signature_info
+retrieves information about the signature of certificate
+.Fa x .
+The NID of the digest algorithm is written to
+.Pf * Fa md_nid ,
+the public key algorithm to
+.Pf * Fa pkey_nid ,
+the effective security bits to
+.Pf * Fa security_bits ,
+and flag details to
+.Pf * Fa flags .
+Any of the output parameters can be set to
+.Dv NULL
+if the information is not required.
+If
+.Fa flags
+is not a
+.Dv NULL
+pointer,
+.Pf * Fa flags
+is set to the bitwise OR of:
+.Bl -tag -width 1n -offset 3n
+.It Dv X509_SIG_INFO_VALID
+No error occurred.
+This flag is set if
+.Fn X509_get_signature_info
+returns 1.
+.It Dv X509_SIG_INFO_TLS
+The signature algorithm is appropriate for use in TLS.
+For a supported EdDSA algorithm (in LibreSSL this is Ed25519)
+this flag is always set.
+For an RSASSA-PSS PSS algorithm this flag is set if
+the parameters are DER encoded,
+the digest algorithm is one of SHA256, SHA384, or SHA512,
+the same digest algorithm is used in the mask generation function,
+and the salt length is equal to the digest algorithm's output length.
+For all other signature algorithms this flag is set if the digest
+algorithm is one of SHA1, SHA256, SHA384, or SHA512.
+.El
+.Pp
+.Fn X509_get_signature_info
+returns 1 on success and 0 on failure.
+Failure conditions include unsupported signature algorithms,
+certificate parsing errors and memory allocation failure.
+.Pp
 These functions provide lower level access to the signature
 for cases where an application wishes to analyse or generate a
 signature in a form where
@@ -211,3 +265,16 @@ All these functions have been available since
 .Fn X509_CRL_get0_tbs_sigalg
 first appeared in LibreSSL 3.7.1 and has been available since
 .Ox 7.3 .
+.Pp
+.Fn X509_get_signature_info
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.6 .
+.Sh CAVEATS
+The security bits returned by
+.Fn X509_get_signature_info
+refer to the information available from the certificate signature
+(such as the signing digest).
+In some cases the actual security of the signature is smaller
+because the signing key is less secure.
+For example in a certificate signed using SHA512
+and a 1024-bit RSA key.