From: Rob Percival <robpercival@google.com>
Date: Mon, 12 Sep 2016 09:28:21 +0000 (+0100)
Subject: Reword documentation for {SCT_CTX/CT_POLICY_EVAL_CTX}_set_time
X-Git-Tag: OpenSSL_1_1_1-pre1~3062
X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=1871a5aa8a538c2b8ac3d302c1e9e72867f5ee0f

Reword documentation for {SCT_CTX/CT_POLICY_EVAL_CTX}_set_time

Do not call the time "current", as a different time can be provided.
For example, a time slightly in the future, to provide tolerance for
CT logs with a clock that is running fast.

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/1554)
---

diff --git a/crypto/ct/ct_locl.h b/crypto/ct/ct_locl.h
index 4b5e344191..9f983c91be 100644
--- a/crypto/ct/ct_locl.h
+++ b/crypto/ct/ct_locl.h
@@ -155,10 +155,11 @@ __owur int SCT_CTX_set1_issuer_pubkey(SCT_CTX *sctx, X509_PUBKEY *pubkey);
 __owur int SCT_CTX_set1_pubkey(SCT_CTX *sctx, X509_PUBKEY *pubkey);
 
 /*
- * Sets the current time, in milliseconds since the Unix epoch.
- * The timestamp of the SCT will be compared to this, to check that it was not
- * issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose
- * timestamp is in the future", so SCT verification will fail in this case.
+ * Sets the time to evaluate the SCT against, in milliseconds since the Unix
+ * epoch. If the SCT's timestamp is after this time, it will be interpreted as
+ * having been issued in the future. RFC6962 states that "TLS clients MUST
+ * reject SCTs whose timestamp is in the future", so an SCT will not validate
+ * in this case.
  */
 void SCT_CTX_set_time(SCT_CTX *sctx, uint64_t time_in_ms);
 
diff --git a/doc/man3/CT_POLICY_EVAL_CTX_new.pod b/doc/man3/CT_POLICY_EVAL_CTX_new.pod
index 0f50078b51..fe25cd9cae 100644
--- a/doc/man3/CT_POLICY_EVAL_CTX_new.pod
+++ b/doc/man3/CT_POLICY_EVAL_CTX_new.pod
@@ -64,11 +64,14 @@ Increments the reference count of the certificate.
 Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the
 CT_POLICY_EVAL_CTX.
 
-=item * CT_POLICY_EVAL_CTX_set_time() to provide the current time
+=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid
 
 The SCT timestamp will be compared to this time to check whether the SCT was
-supposedly issued in the future. RFC6962 states that "TLS clients MUST reject
-SCTs whose timestamp is in the future".
+issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose
+timestamp is in the future". Typically, the time provided to this function will
+be the current time.
+
+The time should be in milliseconds since the Unix epoch.
 
 =back
 
diff --git a/include/openssl/ct.h b/include/openssl/ct.h
index d001fc9b49..bf29fbabe0 100644
--- a/include/openssl/ct.h
+++ b/include/openssl/ct.h
@@ -106,9 +106,9 @@ void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx,
 uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx);
 
 /*
- * Sets the current time, in milliseconds since the Unix epoch.
- * The timestamps of the SCTs will be compared to this, to check that they were
- * not issued in the future. RFC6962 states that "TLS clients MUST reject SCTs
+ * Sets the time to evaluate SCTs against, in milliseconds since the Unix epoch.
+ * If an SCT's timestamp is after this time, it will be interpreted as having
+ * been issued in the future. RFC6962 states that "TLS clients MUST reject SCTs
  * whose timestamp is in the future", so an SCT will not validate in this case.
  */
 void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms);