Skip to content

add additional documentation for X509 headers #1142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 28, 2023
Merged

add additional documentation for X509 headers #1142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 53 additions & 25 deletions include/openssl/x509.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2189,12 +2189,14 @@ DEFINE_STACK_OF(X509_TRUST)
#define X509_TRUST_OCSP_REQUEST 7
#define X509_TRUST_TSA 8

// Keep these up to date!
// Keep these up to date! (hidden)

#define X509_TRUST_MIN 1
#define X509_TRUST_MAX 8


// trust_flags values

#define X509_TRUST_DYNAMIC 1
#define X509_TRUST_DYNAMIC_NAME 2

Expand Down Expand Up @@ -2480,6 +2482,24 @@ OPENSSL_EXPORT int X509_REVOKED_add1_ext_i2d(X509_REVOKED *x, int nid,
void *value, int crit,
unsigned long flags);

// X509_verify_cert attempts to discover and validate a certificate chain based
// on parameters in |ctx|. |ctx| usually includes a target certificate to be
// verified, a set of certificates serving as trust anchors, a list of
// non-trusted certificates that may be helpful for chain construction, flags,
// and various other optional components such as callback functions. A
// certificate chain is built up starting from the target certificate and ending
// in a trust anchor. The chain is built up iteratively, looking up in turn a
// certificate with suitable key usage that matches as an issuer of the current
// "subject" certificate.
//
// NOTE:
// 1. Applications rarely call this function directly, but it is used
// internally for certificate validation.
// 2. When looking for the issuer of a certificate, if the current candidate
// issuer matches the subject certificate, but is expired, AWS-LC will fail
// verification and reject the expired cert. This is inherently different
// from OpenSSL 1.1.1, where they will continue searching until they find a
// non-expired cert to use.
OPENSSL_EXPORT int X509_verify_cert(X509_STORE_CTX *ctx);

// PKCS#8 utilities
Expand Down Expand Up @@ -2680,59 +2700,66 @@ OPENSSL_EXPORT void X509_STORE_CTX_set_depth(X509_STORE_CTX *ctx, int depth);
#define X509_V_ERR_UNSUPPORTED_NAME_SYNTAX 53
#define X509_V_ERR_CRL_PATH_VALIDATION_ERROR 54

// Host, email and IP check errors
// The following indicate Host, email and IP check errors
#define X509_V_ERR_HOSTNAME_MISMATCH 62
#define X509_V_ERR_EMAIL_MISMATCH 63
#define X509_V_ERR_IP_ADDRESS_MISMATCH 64

// Caller error
// X509_V_ERR_INVALID_CALL indicates a caller error.
#define X509_V_ERR_INVALID_CALL 65
// Issuer lookup error
// X509_V_ERR_STORE_LOOKUP indicates an issuer lookup error.
#define X509_V_ERR_STORE_LOOKUP 66

#define X509_V_ERR_NAME_CONSTRAINTS_WITHOUT_SANS 67

// Certificate verify flags

// Send issuer+subject checks to verify_cb
// X509_V_FLAG_CB_ISSUER_CHECK sends issuer+subject checks to |verify_cb|.
#define X509_V_FLAG_CB_ISSUER_CHECK 0x1
// Use check time instead of current time
// X509_V_FLAG_USE_CHECK_TIME uses check time instead of current time.
#define X509_V_FLAG_USE_CHECK_TIME 0x2
// Lookup CRLs
// X509_V_FLAG_CRL_CHECK enables lookup CRLs for the leaf certificate.
#define X509_V_FLAG_CRL_CHECK 0x4
// Lookup CRLs for whole chain
// X509_V_FLAG_CRL_CHECK_ALL enables lookup CRLs for whole chain.
#define X509_V_FLAG_CRL_CHECK_ALL 0x8
// Ignore unhandled critical extensions
// X509_V_FLAG_IGNORE_CRITICAL ignores unhandled critical extensions.
#define X509_V_FLAG_IGNORE_CRITICAL 0x10
// Does nothing as its functionality has been enabled by default.
// X509_V_FLAG_X509_STRICT does nothing as its functionality has been enabled by
// default.
#define X509_V_FLAG_X509_STRICT 0x00
// This flag does nothing as proxy certificate support has been removed.
// X509_V_FLAG_ALLOW_PROXY_CERTS does nothing as proxy certificate support has
// been removed.
#define X509_V_FLAG_ALLOW_PROXY_CERTS 0x40
// Enable policy checking
// X509_V_FLAG_POLICY_CHECK enables policy checking.
#define X509_V_FLAG_POLICY_CHECK 0x80
// Policy variable require-explicit-policy
// X509_V_FLAG_EXPLICIT_POLICY enables the policy variable:
// require-explicit-policy
#define X509_V_FLAG_EXPLICIT_POLICY 0x100
// Policy variable inhibit-any-policy
// X509_V_FLAG_INHIBIT_ANY enables the policy variable: inhibit-any-policy
#define X509_V_FLAG_INHIBIT_ANY 0x200
// Policy variable inhibit-policy-mapping
// X509_V_FLAG_INHIBIT_MAP enables the policy variable: inhibit-policy-mapping
#define X509_V_FLAG_INHIBIT_MAP 0x400
// Notify callback that policy is OK
// X509_V_FLAG_NOTIFY_POLICY notifies the callback that the policy is OK
#define X509_V_FLAG_NOTIFY_POLICY 0x800
// Extended CRL features such as indirect CRLs, alternate CRL signing keys
// X509_V_FLAG_EXTENDED_CRL_SUPPORT enables extended CRL features such as
// indirect CRLs, alternate CRL signing keys.
#define X509_V_FLAG_EXTENDED_CRL_SUPPORT 0x1000
// Delta CRL support
// X509_V_FLAG_USE_DELTAS enables Delta CRL support.
#define X509_V_FLAG_USE_DELTAS 0x2000
// Check selfsigned CA signature
// X509_V_FLAG_CHECK_SS_SIGNATURE enables checking the self signed CA signature.
#define X509_V_FLAG_CHECK_SS_SIGNATURE 0x4000
// Use trusted store first
// X509_V_FLAG_TRUSTED_FIRST flag causes chain construction to look for issuers
// in the trust store before looking at the untrusted certificates provided.
#define X509_V_FLAG_TRUSTED_FIRST 0x8000

// Allow partial chains if at least one certificate is in trusted store
// X509_V_FLAG_PARTIAL_CHAIN allows partial chains if at least one certificate
// is in the trusted store.
#define X509_V_FLAG_PARTIAL_CHAIN 0x80000

// If the initial chain is not trusted, do not attempt to build an alternative
// chain. Alternate chain checking was introduced in 1.0.2b. Setting this flag
// will force the behaviour to match that of previous versions.
// X509_V_FLAG_NO_ALT_CHAINS suppresses checking for alternative chains. If the
// initial chain is not trusted, do not attempt to build an alternative chain.
// Alternate chain checking was introduced in 1.0.2b. Setting this flag will
// force the behaviour to match that of previous versions.
#define X509_V_FLAG_NO_ALT_CHAINS 0x100000

// X509_V_FLAG_NO_CHECK_TIME disables all time checks in certificate
Expand All @@ -2745,7 +2772,8 @@ OPENSSL_EXPORT void X509_STORE_CTX_set_depth(X509_STORE_CTX *ctx, int depth);
#define X509_VP_FLAG_LOCKED 0x8
#define X509_VP_FLAG_ONCE 0x10

// Internal use: mask of policy related options
// Internal use: mask of policy related options (hidden)

#define X509_V_FLAG_POLICY_MASK \
(X509_V_FLAG_POLICY_CHECK | X509_V_FLAG_EXPLICIT_POLICY | \
X509_V_FLAG_INHIBIT_ANY | X509_V_FLAG_INHIBIT_MAP)
Expand Down
3 changes: 2 additions & 1 deletion util/doc.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@
},{
"Name": "Legacy ASN.1 and X.509 implementation (documentation in progress)",
"Headers": [
"include/openssl/asn1.h"
"include/openssl/asn1.h",
"include/openssl/x509.h"
]
},{
"Name": "SSL implementation",
Expand Down