X509_CHECK_PURPOSE(3) | Library Functions Manual | X509_CHECK_PURPOSE(3) |
X509_check_purpose
—
check intended usage of a public key
#include
<openssl/x509v3.h>
int
X509_check_purpose
(X509
*certificate, int purpose, int
ca);
If the ca flag is 0,
X509_check_purpose
()
checks whether the public key contained in the
certificate is intended to be used for the given
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 certificate.
X509_PURPOSE_SSL_CLIENT
NID_client_auth
).digitalSignature
bit is
set.NS_SSL_CLIENT
).X509_PURPOSE_SSL_SERVER
NID_server_auth
) or the private
“Netscape Server Gated Crypto”
(NID_ns_sgc
) or “Microsoft Server Gated
Crypto” (NID_ms_sgc
) purpose.digitalSignature
and
keyEncipherment
bits is set.NS_SSL_SERVER
)X509_PURPOSE_NS_SSL_SERVER
X509_PURPOSE_SSL_SERVER
and additionally requires
that a Key Usage extension, if present, has the
keyEncipherment
bit set.X509_PURPOSE_SMIME_SIGN
NID_email_protect
).digitalSignature
and
nonRepudiation
bits is set.X509_PURPOSE_SMIME_ENCRYPT
NID_email_protect
).keyEncipherment
bit is
set.X509_PURPOSE_CRL_SIGN
cRLSign
bit is set.X509_PURPOSE_ANY
X509_PURPOSE_OCSP_HELPER
X509_PURPOSE_TIMESTAMP_SIGN
digitalSignature
and
nonRepudiation
bits is set, and no other bits
are set.If the ca flag is
non-zero,
X509_check_purpose
()
instead checks whether the certificate can be used as
a certificate authority certificate in the context of the given
purpose. To succeed, the check always requires that
none of the following conditions are violated:
keyCertSign
bit is set.The check succeeds if none of the additional conditions given in the list below are violated.
X509_PURPOSE_SSL_CLIENT
NID_client_auth
).keyCertSign
bit set or a Netscape Cert Type
extension with the “SSL CA certificate” bit set.X509_PURPOSE_SSL_SERVER
or
X509_PURPOSE_NS_SSL_SERVER
NID_server_auth
) or the private
“Netscape Server Gated Crypto”
(NID_ns_sgc
) or “Microsoft Server Gated
Crypto” (NID_ms_sgc
) purpose.keyCertSign
bit set or a Netscape Cert Type
extension with the “SSL CA certificate” bit set.X509_PURPOSE_SMIME_SIGN
or
X509_PURPOSE_SMIME_ENCRYPT
NID_email_protect
).keyCertSign
bit set or a Netscape Cert Type
extension with the “S/MIME CA certificate” bit set.X509_PURPOSE_CRL_SIGN
,
X509_PURPOSE_OCSP_HELPER
, or
X509_PURPOSE_TIMESTAMP_SIGN
keyCertSign
bit set or a Netscape Cert Type
extension with at least one of the “SSL CA certificate”,
“S/MIME CA certificate”, or “Object-signing CA
certificate” bits set.X509_PURPOSE_ANY
If parsing of any extensions that are
present succeeds and the purpose argument is -1,
X509_check_purpose
()
always succeeds, no matter whether or not the ca flag
is set.
If the function
X509_PURPOSE_add(3) was called
before
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
purpose identifiers not listed above.
X509_check_purpose
() returns the following
values:
-1 | Error | Parsing of certificate extensions failed or the purpose is invalid. |
0 | Failure | The certificate cannot be used for the purpose. |
If ca is 0, the following values can also be returned:
1 | Success | The certificate can be used for the purpose. |
2 | Unknown | No decision can be made. |
If ca is non-zero, the following values can also be returned:
1 | Success | The certificate can be used as a CA for the purpose. |
3 | Success | The certificate is a version 1 CA. |
4 | Success | The Key Usage allows keyCertSign . |
5 | Success | A Netscape Cert Type allows usage as a CA. |
BASIC_CONSTRAINTS_new(3), EXTENDED_KEY_USAGE_new(3), X509_check_trust(3), X509_new(3), X509_policy_check(3), X509_PURPOSE_set(3), X509V3_get_d2i(3), x509v3.cnf(5)
RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
X509_check_purpose
() first appeared in
OpenSSL 0.9.5 and has been available since OpenBSD
2.7.
October 29, 2021 | OpenBSD-current |