Documents the SCT validation functions

Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>

diff --git a/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod
index ebed8d9a26053831be8fb9b9a7211b620f9621d8..713bcd29d87a81d4fafb0683f42e3f1d9b2944ba 100644 (file)
--- a/doc/crypto/SCT_validate.pod
+++ b/doc/crypto/SCT_validate.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
-checks Signed Certificate Timestamps meet a Certificate Transparency policy
+checks Signed Certificate Timestamps (SCTs) are valid
 
 =head1 SYNOPSIS
 
@@ -18,21 +18,63 @@ checks Signed Certificate Timestamps meet a Certificate Transparency policy
   SCT_VALIDATION_STATUS_UNKNOWN_VERSION
  } sct_validation_status_t;
 
- sct_validation_status_t SCT_get_validation_status(const SCT *sct);
  int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
  int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
+ sct_validation_status_t SCT_get_validation_status(const SCT *sct);
 
 =head1 DESCRIPTION
 
+SCT_validate() will check that an SCT is valid and verify its signature.
+SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
+The result of the validation checks can be obtained by passing the SCT to
+SCT_get_validation_status().
 
+A CT_POLICY_EVAL_CTX must be provided that specifies:
 
-=head1 NOTES
+=over
+
+=item * The certificate the SCT was issued for.
+
+Failure to provide the certificate will result in the validation status being
+SCT_VALIDATION_STATUS_UNVERIFIED.
+
+=item * The issuer of that certificate.
+
+This is only required if the SCT was issued for a pre-certificate
+(see RFC 6962). If it is required but not provided, the validation status will
+be SCT_VALIDATION_STATUS_UNVERIFIED.
 
+=item * A CTLOG_STORE that contains the CT log that issued this SCT.
 
+If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
+status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
+
+=back
+
+If the SCT is of an unsupported version (only v1 is currently supported), the
+validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
+
+If the SCT's signature is incorrect, the validation status will be
+SCT_VALIDATION_STATUS_INVALID. Otherwise, if all checks have passed, the
+validation status will be SCT_VALIDATION_STATUS_VALID.
+
+=head1 NOTES
+
+A return value of 0 from SCT_LIST_validate() should not be interpreted as a
+failure. At a minimum, only one valid SCT may provide sufficient confidence
+that a certificate has been publicly logged.
 
 =head1 RETURN VALUES
 
+SCT_validate() returns a negative integer if an internal error occurs, 0 if the
+SCT fails validation, or 1 if the SCT passes validation.
+
+SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
+if any of SCTs fails validation, or 1 if they all pass validation.
 
+SCT_get_validation_status() returns the validation status of the SCT.
+If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
+returned value will be SCT_VALIDATION_STATUS_NOT_SET.
 
 =head1 SEE ALSO