document X509_check_purpose(3)

6 files changed, 403 insertions, 9 deletions

diff --git a/lib/libcrypto/man/BASIC_CONSTRAINTS_new.3 b/lib/libcrypto/man/BASIC_CONSTRAINTS_new.3
index 7a04249adb7..cfe6737c415 100644
--- a/lib/libcrypto/man/BASIC_CONSTRAINTS_new.3
+++ b/lib/libcrypto/man/BASIC_CONSTRAINTS_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BASIC_CONSTRAINTS_new.3,v 1.4 2019/06/06 01:06:58 schwarze Exp $
+.\" $OpenBSD: BASIC_CONSTRAINTS_new.3,v 1.5 2019/08/22 15:15:35 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: August 22 2019 $
 .Dt BASIC_CONSTRAINTS_NEW 3
 .Os
 .Sh NAME
@@ -68,6 +68,7 @@ object or
 if an error occurs.
 .Sh SEE ALSO
 .Xr d2i_BASIC_CONSTRAINTS 3 ,
+.Xr X509_check_purpose 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_new 3
 .Sh STANDARDS
diff --git a/lib/libcrypto/man/EXTENDED_KEY_USAGE_new.3 b/lib/libcrypto/man/EXTENDED_KEY_USAGE_new.3
index 4e644b227d6..869f538c6f9 100644
--- a/lib/libcrypto/man/EXTENDED_KEY_USAGE_new.3
+++ b/lib/libcrypto/man/EXTENDED_KEY_USAGE_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: EXTENDED_KEY_USAGE_new.3,v 1.4 2019/06/06 01:06:58 schwarze Exp $
+.\" $OpenBSD: EXTENDED_KEY_USAGE_new.3,v 1.5 2019/08/22 15:15:35 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 6 2019 $
+.Dd $Mdocdate: August 22 2019 $
 .Dt EXTENDED_KEY_USAGE_NEW 3
 .Os
 .Sh NAME
@@ -63,6 +63,7 @@ if an error occurs.
 .Xr BASIC_CONSTRAINTS_new 3 ,
 .Xr d2i_EXTENDED_KEY_USAGE 3 ,
 .Xr POLICYINFO_new 3 ,
+.Xr X509_check_purpose 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_new 3
 .Sh STANDARDS
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 99536f65aa8..c9c74ca3372 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.152 2019/08/20 13:27:19 schwarze Exp $
+# $OpenBSD: Makefile,v 1.153 2019/08/22 15:15:35 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -265,6 +265,7 @@ MAN=	\
 	X509_check_host.3 \
 	X509_check_issued.3 \
 	X509_check_private_key.3 \
+	X509_check_purpose.3 \
 	X509_cmp.3 \
 	X509_cmp_time.3 \
 	X509_digest.3 \
diff --git a/lib/libcrypto/man/X509V3_get_d2i.3 b/lib/libcrypto/man/X509V3_get_d2i.3
index 70a36530ba5..13f1eda35da 100644
--- a/lib/libcrypto/man/X509V3_get_d2i.3
+++ b/lib/libcrypto/man/X509V3_get_d2i.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509V3_get_d2i.3,v 1.16 2019/06/14 13:59:32 schwarze Exp $
+.\" $OpenBSD: X509V3_get_d2i.3,v 1.17 2019/08/22 15:15:35 schwarze Exp $
 .\" full merge up to: OpenSSL ff7fbfd5 Nov 2 11:52:01 2015 +0000
 .\" selective merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 14 2019 $
+.Dd $Mdocdate: August 22 2019 $
 .Dt X509V3_GET_D2I 3
 .Os
 .Sh NAME
@@ -408,6 +408,7 @@ if no extensions are present.
 .Sh SEE ALSO
 .Xr d2i_X509 3 ,
 .Xr d2i_X509_EXTENSION 3 ,
+.Xr X509_check_purpose 3 ,
 .Xr X509_CRL_get0_by_serial 3 ,
 .Xr X509_CRL_new 3 ,
 .Xr X509_EXTENSION_new 3 ,
diff --git a/lib/libcrypto/man/X509_check_purpose.3 b/lib/libcrypto/man/X509_check_purpose.3
new file mode 100644
index 00000000000..b74ea50bef3
--- /dev/null
+++ b/lib/libcrypto/man/X509_check_purpose.3
@@ -0,0 +1,389 @@
+.\" $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 .
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index 25b45b39bda..c7a62c22157 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.19 2019/08/20 13:27:19 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.20 2019/08/22 15:15:35 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 20 2019 $
+.Dd $Mdocdate: August 22 2019 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -146,6 +146,7 @@ if an error occurs.
 .Xr X509_check_host 3 ,
 .Xr X509_check_issued 3 ,
 .Xr X509_check_private_key 3 ,
+.Xr X509_check_purpose 3 ,
 .Xr X509_CINF_new 3 ,
 .Xr X509_cmp 3 ,
 .Xr X509_CRL_new 3 ,