First draft of CT documentation

=pod

=head1 NAME

CTLOG_STORE_get0_log_by_id -

Get a Certificate Transparency log from a CTLOG_STORE

=head1 SYNOPSIS

 #include <openssl/ct.h>

 const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store,

                                         const uint8_t *log_id,

                                         size_t log_id_len);

=head1 DESCRIPTION

A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency

(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2).

Therefore, it is useful to be able to look up more information about a log

(e.g. its public key) using this LogID.

B<CTLOG_STORE_get0_log_by_id>() provides a way to do this. It will find a CTLOG

in a CTLOG_STORE that has a given LogID.

=head1 RETURN VALUES

B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it

exists in the given CTLOG_STORE, otherwise it returns NULL.

=head1 SEE ALSO

L<ct(3)>,

L<CTLOG_STORE_new(3)>

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

 No newline at end of file

=pod

=head1 NAME

CTLOG_STORE_new, CTLOG_STORE_free,

CTLOG_STORE_load_default_file, CTLOG_STORE_load_file -

Create and populate a Certificate Transparency log list

=head1 SYNOPSIS

 #include <openssl/ct.h>

 CTLOG_STORE *CTLOG_STORE_new(void);

 void CTLOG_STORE_free(CTLOG_STORE *store);

 int CTLOG_STORE_load_default_file(CTLOG_STORE *store);

 int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file);

=head1 DESCRIPTION

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).

B<CTLOG_STORE_new>() creates an empty list of CT logs. This is then populated

by B<CTLOG_STORE_load_default_file>() or B<CTLOG_STORE_load_file>().

B<CTLOG_STORE_load_default_file>() loads from the default file, which is named

"ct_log_list.cnf" in the OpenSSL install directory. This can be overridden using

an environment variable named "CTLOG_FILE".

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:

 enabled_logs=foo,bar

 [foo]

 description = Log 1

 key = <base64-encoded public key here>

 [bar]

 description = Log 2

 key = <base64-encoded public key here>

Once a CTLOG_STORE is no longer required, it should be passed to

B<CTLOG_STORE_free>(). This will delete all of the CTLOGs stored within, along

with the CTLOG_STORE itself.

=head1 NOTES

If there are any invalid CT logs in a file, they are skipped and the remaining

valid logs will still be added to the CTLOG_STORE. A CT log will be considered

invalid if it is missing a "key" or "description" field.

=head1 RETURN VALUES

Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if

all CT logs in the file are successfully parsed and loaded, 0 otherwise.

=head1 SEE ALSO

L<ct(3)>,

L<CTLOG_STORE_get0_log_by_id(3)>,

L<SSL_CTX_set_ctlog_list_file(3)>

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

 No newline at end of file

=pod

=head1 NAME

Func -

title

=head1 SYNOPSIS

 #include <openssl/ct.h>

 CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name);

 CTLOG *CTLOG_new_null(void);

 int CTLOG_new_from_base64(CTLOG ** ct_log,

                           const char *pkey_base64, const char *name);

 void CTLOG_free(CTLOG *log);

 const char *CTLOG_get0_name(const CTLOG *log);

 void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id,

                       size_t *log_id_len);

 EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log);

=head1 DESCRIPTION

=head1 NOTES

=head1 RETURN VALUES

=head1 SEE ALSO

L<ct(3)>

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

 No newline at end of file

=pod

=head1 NAME

CT_POLICY_EVAL_CTX -

Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy

=head1 SYNOPSIS

 #include <openssl/ct.h>

 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);

 void CT_POLICY_EVAL_CTX_set0_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert);

 X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx);

 void CT_POLICY_EVAL_CTX_set0_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer);

 const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx);

 void CT_POLICY_EVAL_CTX_set0_log_store(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store);

=head1 DESCRIPTION

A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed

Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy.

This policy may be, for example, that at least one valid SCT is available. To

determine this, an SCT's signature must be verified. This requires:

=over

=item * the public key of the log that issued the SCT

=item * the certificate that the SCT was issued for

=item * the issuer certificate (if the SCT was issued for a pre-certificate)

=back

The above requirements are met using the setters described below.

B<CT_POLICY_EVAL_CTX_new>() creates an empty policy evaluation context. This

should then be populated using:

=over

=item * B<CT_POLICY_EVAL_CTX_set0_cert>() to provide the certificate the SCTs were issued for

=item * B<CT_POLICY_EVAL_CTX_set0_issuer>() to provide the issuer certificate

=item * B<CT_POLICY_EVAL_CTX_set0_log_store>() to provide a list of logs that are trusted as sources of SCTs

=back

None of these setters take ownership of the pointers passed to them.

Each setter has a matching getter for accessing the current value.

The getters do not transfer ownership either.

When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to

B<CT_POLICY_EVAL_CTX_free>() to delete it.

=head1 NOTES

The issuer certificate only needs to be provided if at least one of the SCTs

was issued for a pre-certificate. This will be the case for SCTs embedded in a

certificate (i.e. those in an X.509 extension), but may not be the case for SCTs

found in the TLS SCT extension or OCSP response.

=head1 RETURN VALUES

B<CT_POLICY_EVAL_CTX_new>() will return NULL if malloc fails.

=head1 SEE ALSO

L<ct(3)>

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

 No newline at end of file

=pod

=head1 NAME

SCT - A Certificate Transparency Signed Certificate Timestamp

=head1 SYNOPSIS

 #include <openssl/ct.h>

 SCT *SCT_new(void);

 SCT *SCT_new_from_base64(unsigned char version,

                          const char *logid_base64,

                          ct_log_entry_type_t entry_type,

                          uint64_t timestamp,

                          const char *extensions_base64,

                          const char *signature_base64);

 void SCT_free(SCT *sct);

 void SCT_LIST_free(STACK_OF(SCT) *a);

 sct_version_t SCT_get_version(const SCT *sct);

 int SCT_set_version(SCT *sct, sct_version_t version);

 ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct);

 int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type);

 size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id);

 int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len);

 int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len);

 uint64_t SCT_get_timestamp(const SCT *sct);

 void SCT_set_timestamp(SCT *sct, uint64_t timestamp);

 int SCT_get_signature_nid(const SCT *sct);

 int SCT_set_signature_nid(SCT *sct, int nid);

 size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext);

 void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len);

 int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len);

 size_t SCT_get0_signature(const SCT *sct, unsigned char **sig);

 void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len);

 int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len);

 sct_source_t SCT_get_source(const SCT *sct);

 int SCT_set_source(SCT *sct, sct_source_t source);

=head1 DESCRIPTION

Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2.

They constitute a promise by a Certificate Transparency (CT) log to publicly

record a certificate. By cryptographically verifying that a log did indeed issue

an SCT, some confidence can be gained that the certificate is publicly known.

An internal representation of an SCT can be created in one of two ways.

The first option is to create a blank SCT, using B<SCT_new>(), and then populate

it using:

=over

=item * B<SCT_set_version>() to set the SCT version.

Only SCT_VERSION_V1 is currently supported.

=item * B<SCT_set_log_entry_type>() to set the type of certificate the SCT was issued for:

B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.

B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.

=item * B<SCT_set0_log_id>() or B<SCT_set1_log_id>() to set the LogID of the CT log that the SCT came from.

The former takes ownership, whereas the latter makes a copy.

See RFC 6962, Section 3.2 for the definition of LogID.

=item * B<SCT_set_timestamp>() to set the time the SCT was issued (epoch time in milliseconds).

=item * B<SCT_set_signature_nid>() to set the NID of the signature.

=item * B<SCT_set0_signature>() or B<SCT_set1_signature>() to set the signature itself.

The former takes ownership, whereas the latter makes a copy.

=item * B<SCT_set0_extensions>() or B<SCT_set1_extensions> to provide SCT extensions.

The former takes ownership, whereas the latter makes a copy.

=back

Alternatively, the SCT can be pre-populated from the following data using

B<SCT_new_from_base64>():

=over

=item * The SCT version (only SCT_VERSION_V1 is currently supported).

=item * The LogID (see RFC 6962, Section 3.2), base64 encoded.

=item * The type of certificate the SCT was issued for:

B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate.

B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate.

=item * The time that the SCT was issued (epoch time in milliseconds).

=item * The SCT extensions, base64 encoded.

=item * The SCT signature, base64 encoded.

=back

B<SCT_set_source>() can be used to record where the SCT was found

(TLS extension, X.509 certificate extension or OCSP response). This is not

required for verifying the SCT.

=head1 NOTES

Some of the setters return int, instead of void. These will all return 1 on

success, 0 on failure. They will not make changes on failure.

Most of the setters will reset the validation status of the SCT to

SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_verify(3)>).

B<SCT_set_source>() will call B<SCT_set_log_entry_type>() if the type of

certificate the SCT was issued for can be inferred from where the SCT was found.

For example, an SCT found in an X.509 extension must have been issued for a pre-

certificate.

B<SCT_set_source>() will not refuse unknown values.

=head1 RETURN VALUES

B<SCT_set_version>() returns 1 if the specified version is supported, 0 otherwise.

B<SCT_set_log_entry_type>() returns 1 if the specified log entry type is supported, 0 otherwise.

B<SCT_set0_log_id>() and B<SCT_set1_log_id> return 1 if the specified LogID is a

valid SHA-256 hash, 0 otherwise. Aditionally, B<SCT_set1_log_id> returns 0 if

malloc fails.

B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise.

B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer

is copied successfully, 0 otherwise (i.e. if malloc fails).

B<SCT_set_source> will always return 1.

=head1 SEE ALSO

L<ct(3)>,

L<SCT_verify(3)>,

L<OBJ_nid2obj(3)>

=head1 COPYRIGHT

Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut