diff options
author | Matt Caswell <matt@openssl.org> | 2020-04-01 16:15:39 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2020-04-09 00:00:20 +0100 |
commit | cc45a884bd499e8b84de0c0133746591c3712f4c (patch) | |
tree | 7a4e997c577e9c28aa1dcb67c39c98c791b5bf79 | |
parent | e66c37deb64d4e4ab0c2d63b817760d387eb9ed8 (diff) | |
download | openssl-new-cc45a884bd499e8b84de0c0133746591c3712f4c.tar.gz |
Document the new X509_STORE_CTX_new_with_libctx() function
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11457)
-rw-r--r-- | doc/man3/X509_STORE_CTX_new.pod | 60 |
1 files 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 <openssl/x509_vfy.h> + 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<X509_STORE_CTX> structure for subsequent use by X509_verify_cert(). -X509_STORE_CTX_new() returns a newly initialised B<X509_STORE_CTX> structure. +X509_STORE_CTX_new_with_libctx() returns a newly initialised B<X509_STORE_CTX> +structure associated with the specified library context I<libctx> and property +query string I<propq>. 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<X509_STORE_CTX> structure. The context can then be reused with an new call to X509_STORE_CTX_init(). -X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> +X509_STORE_CTX_free() completely frees up I<ctx>. After this call I<ctx> is no longer valid. -If B<ctx> is NULL nothing is done. +If I<ctx> is NULL nothing is done. -X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. -It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only +X509_STORE_CTX_init() sets up I<ctx> for a subsequent verification operation. +It must be called before each call to X509_verify_cert(), i.e. a I<ctx> is only good for one call to X509_verify_cert(); if you want to verify a second -certificate with the same B<ctx> then you must call X509_STORE_CTX_cleanup() +certificate with the same I<ctx> 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<store>, the end -entity certificate to be verified is set to B<x509> and a set of additional +X509_verify_cert(). The trusted certificate store is set to I<store>, the end +entity certificate to be verified is set to I<x509> and a set of additional certificates (which will be untrusted but may be used to build the chain) in -B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be +I<chain>. Any or all of the I<store>, I<x509> and I<chain> parameters can be B<NULL>. X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of -B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates +I<ctx> to I<sk>. This is an alternative way of specifying trusted certificates instead of using an B<X509_STORE>. -X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to -B<x>. +X509_STORE_CTX_set_cert() sets the certificate to be verified in I<ctx> to +I<x>. X509_STORE_CTX_set0_verified_chain() sets the validated chain used -by B<ctx> to be B<chain>. -Ownership of the chain is transferred to B<ctx> and should not be +by I<ctx> to be I<chain>. +Ownership of the chain is transferred to I<ctx> and should not be free'd by the caller. X509_STORE_CTX_get0_chain() returns a the internal pointer used by the -B<ctx> that contains the validated chain. +I<ctx> that contains the validated chain. X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate -verification to B<sk>. These CRLs will only be used if CRL verification is +verification to I<sk>. These CRLs will only be used if CRL verification is enabled in the associated B<X509_VERIFY_PARAM> 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<ctx>. +to the verification parameters associated with I<ctx>. X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the -stack of untrusted certificates associated with B<ctx>. +stack of untrusted certificates associated with I<ctx>. X509_STORE_CTX_set0_untrusted() sets the internal point to the stack -of untrusted certificates associated with B<ctx> to B<sk>. +of untrusted certificates associated with I<ctx> to I<sk>. X509_STORE_CTX_set0_param() sets the internal verification parameter pointer -to B<param>. After this call B<param> should not be used. +to I<param>. After this call B<param> should not be used. X509_STORE_CTX_set_default() looks up and sets the default verification -method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to -find an appropriate set of parameters from B<name>. +method to I<name>. This uses the function X509_VERIFY_PARAM_lookup() to +find an appropriate set of parameters from I<name>. 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<X509_VERIFY_PARAM_set_flags(3)> 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 |