From a0a9f36ebf70c4705d08eb93e23ae64bd28a0bbd Mon Sep 17 00:00:00 2001 From: Rob Percival Date: Tue, 23 Aug 2016 18:05:28 +0100 Subject: [PATCH] Documents the SCT validation functions Reviewed-by: Rich Salz Reviewed-by: Matt Caswell --- doc/crypto/SCT_validate.pod | 48 ++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/doc/crypto/SCT_validate.pod b/doc/crypto/SCT_validate.pod index ebed8d9a26..713bcd29d8 100644 --- 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 -- GitLab