-.\" $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
.\"
.\" 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
.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
.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 ,
.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
.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.