Document the new library context aware CT functions

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11483)

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 <openssl/ct.h>
 
+ 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<ct_log_list.cnf> in OPENSSLDIR (see the output of L<openssl-version(1)>).
-This can be overridden using an environment variable named B<CTLOG_FILE>.
-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<libctx> and the property query string I<propq>.
+
+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<ct_log_list.cnf> in OPENSSLDIR (see the output of
+L<openssl-version(1)>). This can be overridden using an environment variable
+named B<CTLOG_FILE>. 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<SSL_CTX_set_ctlog_list_file(3)>
 
 =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 <openssl/ct.h>
 
+ 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<libctx> and property query string I<propq>. 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<libctx> and property query
+string I<propq>.
 
-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<ct(7)>
 
 =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 <openssl/ct.h>
 
+ 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<libctx> and property query
+string I<propq>.
+
+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<ct(7)>
 
 =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