.\" $OpenBSD: X509_check_purpose.3,v 1.12 2024/09/02 08:04:32 tb Exp $
.\"
.\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 2 2024 $
.Dt X509_CHECK_PURPOSE 3
.Os
.Sh NAME
.Nm X509_check_purpose
.Nd check intended usage of a public key
.Sh SYNOPSIS
.In openssl/x509v3.h
.Ft int
.Fo X509_check_purpose
.Fa "X509 *certificate"
.Fa "int purpose"
.Fa "int ca"
.Fc
.Sh DESCRIPTION
If the
.Fa purpose
argument is \-1,
.Fn X509_check_purpose
ignores the
.Fa ca
argument and checks that all the extensions of the
.Fa certificate
can be parsed and pass minimal sanity checks, ensuring that
no extension occurs more than once.
It also makes sure that all extensions are cached in the
.Vt X509
object.
.Pp
If the
.Fa purpose
argument is not \-1 and the
.Fa ca
flag is 0,
.Fn X509_check_purpose
also checks whether the public key contained in the
.Fa certificate
is intended to be used for the given
.Fa purpose ,
which can be one of the following integer constants.
The check succeeds if none of the conditions given in the list below
are violated.
It always fails if parsing fails for any extension contained in the
.Fa certificate .
.Bl -tag -width 1n
.It Dv X509_PURPOSE_SSL_CLIENT
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq TLS WWW client authentication
purpose
.Pq Dv NID_client_auth .
.It
If the
.Fa certificate
contains a Key Usage extension, the
.Dv digitalSignature
bit is set.
.It
If the
.Fa certificate
contains a Netscape Cert Type extension, the
.Dq SSL client certificate
bit is set
.Pq Dv NS_SSL_CLIENT .
.El
.It Dv X509_PURPOSE_SSL_SERVER
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq TLS WWW server authentication
purpose
.Pq Dv NID_server_auth
or the private
.Dq Netscape Server Gated Crypto
.Pq Dv NID_ns_sgc
or
.Dq Microsoft Server Gated Crypto
.Pq Dv NID_ms_sgc
purpose.
.It
If the
.Fa certificate
contains a Key Usage extension, at least one of the
.Dv digitalSignature
and
.Dv keyEncipherment
bits is set.
.It
If the
.Fa certificate
contains a Netscape Cert Type extension, the
.Dq SSL server certificate
bit is set
.Pq Dv NS_SSL_SERVER
.El
.It Dv X509_PURPOSE_NS_SSL_SERVER
.\" check_purpose_ns_ssl_server, "Netscape SSL server"
This does the same checks as
.Dv X509_PURPOSE_SSL_SERVER
and additionally requires that a Key Usage extension, if present,
has the
.Dv keyEncipherment
bit set.
.It Dv X509_PURPOSE_SMIME_SIGN
.\" check_purpose_smime_sign, "S/MIME signing"
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq Email protection
purpose
.Pq Dv NID_email_protect .
.It
If the
.Fa certificate
contains a Key Usage extension, at least one of the
.Dv digitalSignature
and
.Dv nonRepudiation
bits is set.
.It
If the
.Fa certificate
contains a Netscape Cert Type extension, it has the
.Dq S/MIME certificate
bit set.
If the
.Dq SSL client certificate
bit is set but the
.Dq S/MIME certificate
bit is not, no decision is made.
.El
.It Dv X509_PURPOSE_SMIME_ENCRYPT
.\" check_purpose_smime_encrypt, "S/MIME encryption"
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq Email protection
purpose
.Pq Dv NID_email_protect .
.It
If the
.Fa certificate
contains a Key Usage extension, the
.Dv keyEncipherment
bit is set.
.It
If the
.Fa certificate
contains a Netscape Cert Type extension, it has the
.Dq S/MIME certificate
bit set.
If the
.Dq SSL client certificate
bit is set but the
.Dq S/MIME certificate
bit is not, no decision is made.
.El
.It Dv X509_PURPOSE_CRL_SIGN
.\" check_purpose_crl_sign, "CRL signing"
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains a Key Usage extension, the
.Dv cRLSign
bit is set.
.El
.It Dv X509_PURPOSE_ANY
Nothing is required except that, if any extensions are present,
parsing them needs to succeed.
.It Dv X509_PURPOSE_OCSP_HELPER
.\" ocsp_helper, "OCSP helper"
Nothing is required except that, if any extensions are present,
parsing them needs to succeed.
The application program is expected
to do the actual checking by other means.
.It Dv X509_PURPOSE_TIMESTAMP_SIGN
.\" check_purpose_timestamp_sign, "Time Stamp signing"
.Bl -dash -width 1n -compact
.It
The
.Fa certificate
contains an Extended Key Usage extension containing the RFC 5280
.Dq Time Stamping
purpose and no other purpose.
This extension is marked as critical.
.It
If the
.Fa certificate
contains a Key Usage extension, at least one of the
.Dv digitalSignature
and
.Dv nonRepudiation
bits is set, and no other bits are set.
.El
.El
.Pp
If the
.Fa purpose
argument is not \-1 and the
.Fa ca
flag is non-zero,
.Fn X509_check_purpose
instead checks, in addition to the minimal sanity checks, whether the
.Fa certificate
can be used as a certificate authority certificate
in the context of the given
.Fa purpose .
To succeed, the check always requires that none of the following
conditions are violated:
.Pp
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains any extensions, parsing them succeeds.
.It
If the
.Fa certificate
contains a Key Usage extension, the
.Dv keyCertSign
bit is set.
.It
If the
.Fa certificate
contains a Basic Constraints extension, the
.Fa cA
field is set.
.It
If the
.Fa certificate
is a version 1 certificate, the subject name matches the issuer name
and the certificate is self signed.
.El
.Pp
The check succeeds if none of the additional conditions given in
the list below are violated.
.Bl -tag -width 1n
.It Dv X509_PURPOSE_SSL_CLIENT
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq TLS WWW client authentication
purpose
.Pq Dv NID_client_auth .
.It
If the
.Fa certificate
is not a version 1 certificate and does not contain a Basic Constraints
extension, it contains a Key Usage extension with the
.Dv keyCertSign
bit set or a Netscape Cert Type extension with the
.Dq SSL CA certificate
bit set.
.El
.It Dv X509_PURPOSE_SSL_SERVER No or Dv X509_PURPOSE_NS_SSL_SERVER
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq TLS WWW server authentication
purpose
.Pq Dv NID_server_auth
or the private
.Dq Netscape Server Gated Crypto
.Pq Dv NID_ns_sgc
or
.Dq Microsoft Server Gated Crypto
.Pq Dv NID_ms_sgc
purpose.
.It
If the
.Fa certificate
is not a version 1 certificate and does not contain a Basic Constraints
extension, it contains a Key Usage extension with the
.Dv keyCertSign
bit set or a Netscape Cert Type extension with the
.Dq SSL CA certificate
bit set.
.El
.It Dv X509_PURPOSE_SMIME_SIGN No or Dv X509_PURPOSE_SMIME_ENCRYPT
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
contains an Extended Key Usage extension, it contains the RFC 5280
.Dq Email protection
purpose
.Pq Dv NID_email_protect .
.It
If the
.Fa certificate
is not a version 1 certificate and does not contain a Basic Constraints
extension, it contains a Key Usage extension with the
.Dv keyCertSign
bit set or a Netscape Cert Type extension with the
.Dq S/MIME CA certificate
bit set.
.El
.It Xo
.Dv X509_PURPOSE_CRL_SIGN ,
.Dv X509_PURPOSE_OCSP_HELPER ,
or
.Dv X509_PURPOSE_TIMESTAMP_SIGN
.Xc
.Bl -dash -width 1n -compact
.It
If the
.Fa certificate
is not a version 1 certificate and does not contain a Basic Constraints
extension, it contains a Key Usage extension with the
.Dv keyCertSign
bit set or a Netscape Cert Type extension with at least one of the
.Dq SSL CA certificate ,
.Dq S/MIME CA certificate ,
or
.Dq Object-signing CA certificate
bits set.
.El
.It Dv X509_PURPOSE_ANY
Nothing is required except that, if any extensions are present,
parsing them needs to succeed.
The check even succeeds if the three other common conditions
cited above this list are violated.
.El
.Pp
If the function
.Xr X509_PURPOSE_add 3
was called before
.Fn X509_check_purpose ,
it may have installed different, user-supplied checking functions
for some of the standard purposes listed above, or it may have
installed additional, user-supplied checking functions for user-defined
.Fa purpose
identifiers not listed above.
.Sh RETURN VALUES
If the parsing of certificate extensions fails, sanity checks fail or the
.Fa purpose
is invalid,
.Fn X509_check_purpose
returns \-1 to indicate the error.
.Pp
If the
.Fa purpose
argument is \-1 and parsing and minimal sanity checks succeed,
.Fn X509_check_purpose
returns 1 to indicate success.
.Pp
Otherwise, it returns the following values:
.Pp
If
.Fa ca
is 0:
.Bl -column -1 Failure -compact
.It 0 Ta Failure Ta The
.Fa certificate
cannot be used for the
.Fa purpose .
.It 1 Ta Success Ta The
.Fa certificate
can be used for the
.Fa purpose .
.It 2 Ta Unknown Ta \&No decision can be made.
.El
.Pp
If
.Fa ca
is non-zero:
.Bl -column -1 Failure -compact
.It 0 Ta Failure Ta The
.Fa certificate
cannot be used as a CA for the
.Fa purpose .
.It 1 Ta Success Ta The
.Fa certificate
can be used as a CA for the
.Fa purpose .
.It 3 Ta Success Ta The Fa certificate No is a version 1 CA .
.It 4 Ta Success Ta The Key Usage allows Dv keyCertSign .
.It 5 Ta Success Ta A Netscape Cert Type allows usage as a CA.
.El
.Sh SEE ALSO
.Xr BASIC_CONSTRAINTS_new 3 ,
.Xr EXTENDED_KEY_USAGE_new 3 ,
.Xr X509_new 3 ,
.Xr X509_PURPOSE_set 3 ,
.Xr X509V3_get_d2i 3 ,
.Xr x509v3.cnf 5
.Sh STANDARDS
RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
Certificate Revocation List (CRL) Profile
.Bl -dash -offset indent -compact
.It
section 4.2.1.3: Key Usage
.It
section 4.2.1.9: Basic Constraints
.It
section 4.2.1.12: Extended Key Usage
.El
.Sh HISTORY
.Fn X509_check_purpose
first appeared in OpenSSL 0.9.5 and has been available since
.Ox 2.7 .