.\" $OpenBSD: X509_check_purpose.3,v 1.1 2019/08/22 15:15:35 schwarze Exp $
.\" Copyright (c) 2019 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: August 22 2019 $
.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 ca
flag is 0,
.Fn X509_check_purpose
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.
.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
The check always succeeds.
.It Dv X509_PURPOSE_OCSP_HELPER
.\" ocsp_helper, "OCSP helper"
The check always succeeds.
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 ca
flag is non-zero,
.Fn X509_check_purpose
instead 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 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
The check always succeeds, even if the three common conditions
cited above this list are violated.
.El
.Pp
If the
.Fa purpose
is -1,
.Fn X509_check_purpose
always succeeds, no matter whether or not the
.Fa ca
flag is set.
.Sh RETURN VALUES
.Fn X509_check_purpose
returns the following values:
.Bl -column -1 Failure -compact
.It -1 Ta Error Ta The
.Fa purpose
is invalid.
.It 0 Ta Failure Ta The
.Fa certificate
cannot be used for the
.Fa purpose .
.El
.Pp
If
.Fa ca
is 0, the following values can also be returned:
.Bl -column -1 Failure -compact
.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, the following values can also be returned:
.Bl -column -1 Failure -compact
.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 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 .