mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-18 20:40:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Document the new library context aware CT functions

Browse Source 
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11483)
This commit is contained in:
Matt Caswell 2020-04-07 17:37:39 +01:00
parent 1a37ee9402
commit aa233ef7f7
3 changed files with 61 additions and 21 deletions

26
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

36
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_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() 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() 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

20
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