228 lines
8.4 KiB
HTML
Executable File
228 lines
8.4 KiB
HTML
Executable File
<?xml version="1.0" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>SCT_new</title>
|
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
|
<link rev="made" href="mailto:root@localhost" />
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
|
|
<!-- INDEX BEGIN -->
|
|
<div name="index">
|
|
<p><a name="__index__"></a></p>
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#notes">NOTES</a></li>
|
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
|
<li><a href="#see_also">SEE ALSO</a></li>
|
|
<li><a href="#history">HISTORY</a></li>
|
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
|
</ul>
|
|
|
|
<hr name="index" />
|
|
</div>
|
|
<!-- INDEX END -->
|
|
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free,
|
|
SCT_get_version, SCT_set_version,
|
|
SCT_get_log_entry_type, SCT_set_log_entry_type,
|
|
SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id,
|
|
SCT_get_timestamp, SCT_set_timestamp,
|
|
SCT_get_signature_nid, SCT_set_signature_nid,
|
|
SCT_get0_signature, SCT_set0_signature, SCT_set1_signature,
|
|
SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions,
|
|
SCT_get_source, SCT_set_source
|
|
- A Certificate Transparency Signed Certificate Timestamp</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
#include <openssl/ct.h></pre>
|
|
<pre>
|
|
typedef enum {
|
|
CT_LOG_ENTRY_TYPE_NOT_SET = -1,
|
|
CT_LOG_ENTRY_TYPE_X509 = 0,
|
|
CT_LOG_ENTRY_TYPE_PRECERT = 1
|
|
} ct_log_entry_type_t;</pre>
|
|
<pre>
|
|
typedef enum {
|
|
SCT_VERSION_NOT_SET = -1,
|
|
SCT_VERSION_V1 = 0
|
|
} sct_version_t;</pre>
|
|
<pre>
|
|
typedef enum {
|
|
SCT_SOURCE_UNKNOWN,
|
|
SCT_SOURCE_TLS_EXTENSION,
|
|
SCT_SOURCE_X509V3_EXTENSION,
|
|
SCT_SOURCE_OCSP_STAPLED_RESPONSE
|
|
} sct_source_t;</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
void SCT_free(SCT *sct);
|
|
void SCT_LIST_free(STACK_OF(SCT) *a);</pre>
|
|
<pre>
|
|
sct_version_t SCT_get_version(const SCT *sct);
|
|
int SCT_set_version(SCT *sct, sct_version_t version);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
uint64_t SCT_get_timestamp(const SCT *sct);
|
|
void SCT_set_timestamp(SCT *sct, uint64_t timestamp);</pre>
|
|
<pre>
|
|
int SCT_get_signature_nid(const SCT *sct);
|
|
int SCT_set_signature_nid(SCT *sct, int nid);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
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);</pre>
|
|
<pre>
|
|
sct_source_t SCT_get_source(const SCT *sct);
|
|
int SCT_set_source(SCT *sct, sct_source_t source);</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>Signed Certificate Timestamps (SCTs) are defined by <a href="http://www.ietf.org/rfc/rfc6962.txt" class="rfc">RFC 6962</a>, 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.</p>
|
|
<p>An internal representation of an SCT can be created in one of two ways.
|
|
The first option is to create a blank SCT, using <code>SCT_new()</code>, and then populate
|
|
it using:</p>
|
|
<ul>
|
|
<li>
|
|
<p><code>SCT_set_version()</code> to set the SCT version.</p>
|
|
<p>Only SCT_VERSION_V1 is currently supported.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>SCT_set_log_entry_type()</code> to set the type of certificate the SCT was issued for:</p>
|
|
<p><strong>CT_LOG_ENTRY_TYPE_X509</strong> for a normal certificate.
|
|
<strong>CT_LOG_ENTRY_TYPE_PRECERT</strong> for a pre-certificate.</p>
|
|
</li>
|
|
<li>
|
|
<p>SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from.</p>
|
|
<p>The former takes ownership, whereas the latter makes a copy.
|
|
See <a href="http://www.ietf.org/rfc/rfc6962.txt" class="rfc">RFC 6962</a>, Section 3.2 for the definition of LogID.</p>
|
|
</li>
|
|
<li>
|
|
<p><code>SCT_set_timestamp()</code> to set the time the SCT was issued (epoch time in milliseconds).</p>
|
|
</li>
|
|
<li>
|
|
<p><code>SCT_set_signature_nid()</code> to set the NID of the signature.</p>
|
|
</li>
|
|
<li>
|
|
<p>SCT_set0_signature() or SCT_set1_signature() to set the raw signature value.</p>
|
|
<p>The former takes ownership, whereas the latter makes a copy.</p>
|
|
</li>
|
|
<li>
|
|
<p>SCT_set0_extensions() or <strong>SCT_set1_extensions</strong> to provide SCT extensions.</p>
|
|
<p>The former takes ownership, whereas the latter makes a copy.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Alternatively, the SCT can be pre-populated from the following data using
|
|
SCT_new_from_base64():</p>
|
|
<ul>
|
|
<li>
|
|
<p>The SCT version (only SCT_VERSION_V1 is currently supported).</p>
|
|
</li>
|
|
<li>
|
|
<p>The LogID (see <a href="http://www.ietf.org/rfc/rfc6962.txt" class="rfc">RFC 6962</a>, Section 3.2), base64 encoded.</p>
|
|
</li>
|
|
<li>
|
|
<p>The type of certificate the SCT was issued for:
|
|
<strong>CT_LOG_ENTRY_TYPE_X509</strong> for a normal certificate.
|
|
<strong>CT_LOG_ENTRY_TYPE_PRECERT</strong> for a pre-certificate.</p>
|
|
</li>
|
|
<li>
|
|
<p>The time that the SCT was issued (epoch time in milliseconds).</p>
|
|
</li>
|
|
<li>
|
|
<p>The SCT extensions, base64 encoded.</p>
|
|
</li>
|
|
<li>
|
|
<p>The SCT signature, base64 encoded.</p>
|
|
</li>
|
|
</ul>
|
|
<p><code>SCT_set_source()</code> 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.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="notes">NOTES</a></h1>
|
|
<p>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.</p>
|
|
<p>All of the setters will reset the validation status of the SCT to
|
|
SCT_VALIDATION_STATUS_NOT_SET (see <em>SCT_validate(3)</em>).</p>
|
|
<p><code>SCT_set_source()</code> will call <code>SCT_set_log_entry_type()</code> 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.</p>
|
|
<p><code>SCT_set_source()</code> will not refuse unknown values.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
|
<p><code>SCT_set_version()</code> returns 1 if the specified version is supported, 0 otherwise.</p>
|
|
<p><code>SCT_set_log_entry_type()</code> returns 1 if the specified log entry type is supported, 0 otherwise.</p>
|
|
<p>SCT_set0_log_id() and <strong>SCT_set1_log_id</strong> return 1 if the specified LogID is a
|
|
valid SHA-256 hash, 0 otherwise. Additionally, <strong>SCT_set1_log_id</strong> returns 0 if
|
|
malloc fails.</p>
|
|
<p><strong>SCT_set_signature_nid</strong> returns 1 if the specified NID is supported, 0 otherwise.</p>
|
|
<p><strong>SCT_set1_extensions</strong> and <strong>SCT_set1_signature</strong> return 1 if the supplied buffer
|
|
is copied successfully, 0 otherwise (i.e. if malloc fails).</p>
|
|
<p><strong>SCT_set_source</strong> returns 1 on success, 0 otherwise.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
|
<p><em>ct(7)</em>,
|
|
<em>SCT_validate(3)</em>,
|
|
<em>OBJ_nid2obj(3)</em></p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="history">HISTORY</a></h1>
|
|
<p>These functions were added in OpenSSL 1.1.0.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
|
<p>Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.</p>
|
|
<p>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
|
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|