Reword documentation for {SCT_CTX/CT_POLICY_EVAL_CTX}_set_time
authorRob Percival <robpercival@google.com>
Mon, 12 Sep 2016 09:28:21 +0000 (10:28 +0100)
committerRich Salz <rsalz@openssl.org>
Tue, 15 Nov 2016 21:12:41 +0000 (16:12 -0500)
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)

crypto/ct/ct_locl.h
doc/man3/CT_POLICY_EVAL_CTX_new.pod
include/openssl/ct.h

index 4b5e344..9f983c9 100644 (file)
@@ -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);
 
 /*
 __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);
 
  */
 void SCT_CTX_set_time(SCT_CTX *sctx, uint64_t time_in_ms);
 
index 0f50078..fe25cd9 100644 (file)
@@ -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.
 
 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
 
 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
 
 
 =back
 
index d001fc9..bf29fba 100644 (file)
@@ -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);
 
 /*
 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);
  * 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);