From cc45a884bd499e8b84de0c0133746591c3712f4c Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Wed, 1 Apr 2020 16:15:39 +0100 Subject: [PATCH] Document the new X509_STORE_CTX_new_with_libctx() function Reviewed-by: Richard Levitte Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/11457) --- doc/man3/X509_STORE_CTX_new.pod | 60 +++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/doc/man3/X509_STORE_CTX_new.pod b/doc/man3/X509_STORE_CTX_new.pod index 3f10a5189b..5217a67dff 100644 --- a/doc/man3/X509_STORE_CTX_new.pod +++ b/doc/man3/X509_STORE_CTX_new.pod @@ -2,9 +2,9 @@ =head1 NAME -X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, -X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, -X509_STORE_CTX_set0_crls, +X509_STORE_CTX_new_with_libctx, X509_STORE_CTX_new, X509_STORE_CTX_cleanup, +X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, +X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, @@ -18,6 +18,8 @@ X509_STORE_CTX_verify_fn #include + X509_STORE_CTX *X509_STORE_CTX_new_with_libctx(OPENSSL_CTX *libctx, + const char *propq); X509_STORE_CTX *X509_STORE_CTX_new(void); void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); void X509_STORE_CTX_free(X509_STORE_CTX *ctx); @@ -49,61 +51,68 @@ X509_STORE_CTX_verify_fn These functions initialise an B structure for subsequent use by X509_verify_cert(). -X509_STORE_CTX_new() returns a newly initialised B structure. +X509_STORE_CTX_new_with_libctx() returns a newly initialised B +structure associated with the specified library context I and property +query string I. Any cryptographic algorithms fetched while performing +processing with the X509_STORE_CTX will use that library context and property +query string. + +X509_STORE_CTX_new() is the same as X509_STORE_CTX_new_with_libctx() except that +the default library context and a NULL property query string are used. X509_STORE_CTX_cleanup() internally cleans up an B structure. The context can then be reused with an new call to X509_STORE_CTX_init(). -X509_STORE_CTX_free() completely frees up B. After this call B +X509_STORE_CTX_free() completely frees up I. After this call I is no longer valid. -If B is NULL nothing is done. +If I is NULL nothing is done. -X509_STORE_CTX_init() sets up B for a subsequent verification operation. -It must be called before each call to X509_verify_cert(), i.e. a B is only +X509_STORE_CTX_init() sets up I for a subsequent verification operation. +It must be called before each call to X509_verify_cert(), i.e. a I is only good for one call to X509_verify_cert(); if you want to verify a second -certificate with the same B then you must call X509_STORE_CTX_cleanup() +certificate with the same I then you must call X509_STORE_CTX_cleanup() and then X509_STORE_CTX_init() again before the second call to -X509_verify_cert(). The trusted certificate store is set to B, the end -entity certificate to be verified is set to B and a set of additional +X509_verify_cert(). The trusted certificate store is set to I, the end +entity certificate to be verified is set to I and a set of additional certificates (which will be untrusted but may be used to build the chain) in -B. Any or all of the B, B and B parameters can be +I. Any or all of the I, I and I parameters can be B. X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of -B to B. This is an alternative way of specifying trusted certificates +I to I. This is an alternative way of specifying trusted certificates instead of using an B. -X509_STORE_CTX_set_cert() sets the certificate to be verified in B to -B. +X509_STORE_CTX_set_cert() sets the certificate to be verified in I to +I. X509_STORE_CTX_set0_verified_chain() sets the validated chain used -by B to be B. -Ownership of the chain is transferred to B and should not be +by I to be I. +Ownership of the chain is transferred to I and should not be free'd by the caller. X509_STORE_CTX_get0_chain() returns a the internal pointer used by the -B that contains the validated chain. +I that contains the validated chain. X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate -verification to B. These CRLs will only be used if CRL verification is +verification to I. These CRLs will only be used if CRL verification is enabled in the associated B structure. This might be used where additional "useful" CRLs are supplied as part of a protocol, for example in a PKCS#7 structure. X509_STORE_CTX_get0_param() retrieves an internal pointer -to the verification parameters associated with B. +to the verification parameters associated with I. X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the -stack of untrusted certificates associated with B. +stack of untrusted certificates associated with I. X509_STORE_CTX_set0_untrusted() sets the internal point to the stack -of untrusted certificates associated with B to B. +of untrusted certificates associated with I to I. X509_STORE_CTX_set0_param() sets the internal verification parameter pointer -to B. After this call B should not be used. +to I. After this call B should not be used. X509_STORE_CTX_set_default() looks up and sets the default verification -method to B. This uses the function X509_VERIFY_PARAM_lookup() to -find an appropriate set of parameters from B. +method to I. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from I. X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates that were used in building the chain following a call to X509_verify_cert(). @@ -161,6 +170,7 @@ L The X509_STORE_CTX_set0_crls() function was added in OpenSSL 1.0.0. The X509_STORE_CTX_get_num_untrusted() function was added in OpenSSL 1.1.0. +The X509_STORE_CTX_new_with_libctx() function was added in OpenSSL 3.0. =head1 COPYRIGHT -- 2.25.1