From aa233ef7f7e5ab7e9de236f56f067cdc186601da Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 7 Apr 2020 17:37:39 +0100 Subject: [PATCH] Document the new library context aware CT functions Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/11483) --- doc/man3/CTLOG_STORE_new.pod | 26 ++++++++++++++------- doc/man3/CTLOG_new.pod | 36 +++++++++++++++++++++-------- doc/man3/CT_POLICY_EVAL_CTX_new.pod | 20 ++++++++++++---- 3 files changed, 61 insertions(+), 21 deletions(-) diff --git a/doc/man3/CTLOG_STORE_new.pod b/doc/man3/CTLOG_STORE_new.pod index f4a21e4b56..196a327868 100644 --- a/doc/man3/CTLOG_STORE_new.pod +++ b/doc/man3/CTLOG_STORE_new.pod @@ -2,6 +2,7 @@ =head1 NAME +CTLOG_STORE_new_with_libctx, CTLOG_STORE_new, CTLOG_STORE_free, CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - Create and populate a Certificate Transparency log list @@ -10,6 +11,8 @@ Create and populate a Certificate Transparency log list #include + CTLOG_STORE *CTLOG_STORE_new_with_libctx(OPENSSL_CTX *libctx, + const char *propq); CTLOG_STORE *CTLOG_STORE_new(void); void CTLOG_STORE_free(CTLOG_STORE *store); @@ -22,13 +25,19 @@ A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency logs). The list can be loaded from one or more files and then searched by LogID (see RFC 6962, Section 3.2, for the definition of a LogID). -CTLOG_STORE_new() creates an empty list of CT logs. This is then populated -by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). -CTLOG_STORE_load_default_file() loads from the default file, which is named -F in OPENSSLDIR (see the output of L). -This can be overridden using an environment variable named B. -CTLOG_STORE_load_file() loads from a caller-specified file path instead. -Both of these functions append any loaded CT logs to the CTLOG_STORE. +CTLOG_STORE_new_with_libctx() creates an empty list of CT logs associated with +the library context I and the property query string I. + +CTLOG_STORE_new() does the same thing as CTLOG_STORE_new_with_libctx() but with +the default library context and property query string. + +The CTLOG_STORE is then populated by CTLOG_STORE_load_default_file() or +CTLOG_STORE_load_file(). CTLOG_STORE_load_default_file() loads from the default +file, which is named F in OPENSSLDIR (see the output of +L). This can be overridden using an environment variable +named B. CTLOG_STORE_load_file() loads from a caller-specified file +path instead. Both of these functions append any loaded CT logs to the +CTLOG_STORE. The expected format of the file is: @@ -65,7 +74,8 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.1.0. +CTLOG_STORE_new_with_libctx was added in OpenSSL 3.0. All other functions were +added in OpenSSL 1.1.0. =head1 COPYRIGHT diff --git a/doc/man3/CTLOG_new.pod b/doc/man3/CTLOG_new.pod index 1c31f337ce..aa5ec0a73a 100644 --- a/doc/man3/CTLOG_new.pod +++ b/doc/man3/CTLOG_new.pod @@ -2,7 +2,8 @@ =head1 NAME -CTLOG_new, CTLOG_new_from_base64, CTLOG_free, +CTLOG_new_with_libctx, CTLOG_new, CTLOG_new_from_base64, +CTLOG_new_from_base64_with_libctx, CTLOG_free, CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key - encapsulates information about a Certificate Transparency log @@ -10,7 +11,13 @@ encapsulates information about a Certificate Transparency log #include + CTLOG *CTLOG_new_with_libctx(EVP_PKEY *public_key, const char *name, + OPENSSL_CTX *libctx, const char *propq); CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name); + + int CTLOG_new_from_base64_with_libctx(CTLOG **ct_log, const char *pkey_base64, + const char *name, OPENSSL_CTX *libctx, + const char *propq); int CTLOG_new_from_base64(CTLOG ** ct_log, const char *pkey_base64, const char *name); void CTLOG_free(CTLOG *log); @@ -21,14 +28,24 @@ encapsulates information about a Certificate Transparency log =head1 DESCRIPTION -CTLOG_new() returns a new CTLOG that represents the Certificate Transparency -(CT) log with the given public key. A name must also be provided that can be -used to help users identify this log. Ownership of the public key is -transferred. +CTLOG_new_with_libctx() returns a new CTLOG that represents the Certificate +Transparency (CT) log with the given public key and associates it with the +library context I and property query string I. A name must also +be provided that can be used to help users identify this log. Ownership of the +public key is transferred. + +CTLOG_new() does the same thing as CTLOG_new_with_libctx() but with the default +library context and the default property query string. + +CTLOG_new_from_base64_with_libctx() also creates a new CTLOG, but takes the +public key in base64-encoded DER form and sets the ct_log pointer to point to +the new CTLOG. The base64 will be decoded and the public key parsed. The CTLOG +will be associated with the given library context I and property query +string I. -CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in -base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG. -The base64 will be decoded and the public key parsed. +CTLOG_new_from_base64() does the same thing as +CTLOG_new_from_base64_with_libctx() except that the default library context and +property query string are used. Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer @@ -58,7 +75,8 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.1.0. +The functions CTLOG_new_with_libctx() and CTLOG_new_from_base64_with_libctx() +were added in OpenSSL 3.0. All other functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT diff --git a/doc/man3/CT_POLICY_EVAL_CTX_new.pod b/doc/man3/CT_POLICY_EVAL_CTX_new.pod index 27c04e19e9..38076352a0 100644 --- a/doc/man3/CT_POLICY_EVAL_CTX_new.pod +++ b/doc/man3/CT_POLICY_EVAL_CTX_new.pod @@ -2,6 +2,7 @@ =head1 NAME +CT_POLICY_EVAL_CTX_new_with_libctx, CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, @@ -13,6 +14,8 @@ Encapsulates the data required to evaluate whether SCTs meet a Certificate Trans #include + CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_with_libctx(OPENSSL_CTX *libctx, + const char *propq); CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); @@ -55,8 +58,15 @@ the current time The above requirements are met using the setters described below. -CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This -should then be populated using: +CT_POLICY_EVAL_CTX_new_with_libctx() creates an empty policy evaluation context +and associates it with the given library context I and property query +string I. + +CT_POLICY_EVAL_CTX_new() does the same thing as +CT_POLICY_EVAL_CTX_new_with_libctx() except that it uses the default library +context and property query string. + +The CT_POLICY_EVAL_CTX should then be populated using: =over 2 @@ -106,7 +116,8 @@ found in the TLS SCT extension or OCSP response. =head1 RETURN VALUES -CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. +CT_POLICY_EVAL_CTX_new_with_libctx() and CT_POLICY_EVAL_CTX_new() will return +NULL if malloc fails. =head1 SEE ALSO @@ -114,7 +125,8 @@ L =head1 HISTORY -These functions were added in OpenSSL 1.1.0. +CT_POLICY_EVAL_CTX_new_with_libctx was added in OpenSSL 3.0. All other +functions were added in OpenSSL 1.1.0. =head1 COPYRIGHT -- 2.25.1