Commit 5edcadb1 authored by Rob Percival's avatar Rob Percival Committed by Matt Caswell
Browse files

Documents the CTLOG functions 



CTLOG_new_null() has been removed from the code, so it has also been
removed from this POD.

Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
parent 0e74d7ca

doc/crypto/CTLOG_new.pod

+25 −4
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 


=head1 NAME



CTLOG_new, CTLOG_new_null, CTLOG_new_from_base64, CTLOG_free,

CTLOG_new, CTLOG_new_from_base64, CTLOG_free,

CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key -

encapsulates information about a Certificate Transparency log
@@ -11,7 +11,6 @@ encapsulates information about a Certificate Transparency log 
 #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);
@@ -22,15 +21,37 @@ 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_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.



=head1 NOTES

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

needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that

was passed to it.



CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was

created. Ownership of the string remains with the CTLOG.



CTLOG_get0_log_id() sets *log_id to point to a string containing that log's

LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a

v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of

the string remains with the CTLOG.



CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the

EVP_PKEY remains with the CTLOG.

with



=head1 RETURN VALUES



CTLOG_new() will return NULL if an error occurs.



CTLOG_new_from_base64() will return 1 on success, 0 otherwise.



=head1 SEE ALSO

include/openssl/ct.h

+1 −0
Original line number Diff line number Diff line
@@ -388,6 +388,7 @@ SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len); 


/*

 * Creates a new CT log instance with the given |public_key| and |name|.

 * Takes ownership of |public_key| but copies |name|.

 * Returns NULL if malloc fails or if |public_key| cannot be converted to DER.

 * Should be deleted by the caller using CTLOG_free when no longer needed.

 */