doc/man3/SCT_validate.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SCT_validate, SCT_LIST_validate, SCT_get_validation_status -
   6 checks Signed Certificate Timestamps (SCTs) are valid
   7
   8 =head1 SYNOPSIS
   9
  10  #include <openssl/ct.h>
  11
  12  typedef enum {
  13      SCT_VALIDATION_STATUS_NOT_SET,
  14      SCT_VALIDATION_STATUS_UNKNOWN_LOG,
  15      SCT_VALIDATION_STATUS_VALID,
  16      SCT_VALIDATION_STATUS_INVALID,
  17      SCT_VALIDATION_STATUS_UNVERIFIED,
  18      SCT_VALIDATION_STATUS_UNKNOWN_VERSION
  19  } sct_validation_status_t;
  20
  21  int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx);
  22  int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx);
  23  sct_validation_status_t SCT_get_validation_status(const SCT *sct);
  24
  25 =head1 DESCRIPTION
  26
  27 SCT_validate() will check that an SCT is valid and verify its signature.
  28 SCT_LIST_validate() performs the same checks on an entire stack of SCTs.
  29 The result of the validation checks can be obtained by passing the SCT to
  30 SCT_get_validation_status().
  31
  32 A CT_POLICY_EVAL_CTX must be provided that specifies:
  33
  34 =over 2
  35
  36 =item *
  37
  38 The certificate the SCT was issued for.
  39
  40 Failure to provide the certificate will result in the validation status being
  41 SCT_VALIDATION_STATUS_UNVERIFIED.
  42
  43 =item *
  44
  45 The issuer of that certificate.
  46
  47 This is only required if the SCT was issued for a pre-certificate
  48 (see RFC 6962). If it is required but not provided, the validation status will
  49 be SCT_VALIDATION_STATUS_UNVERIFIED.
  50
  51 =item *
  52
  53 A CTLOG_STORE that contains the CT log that issued this SCT.
  54
  55 If the SCT was issued by a log that is not in this CTLOG_STORE, the validation
  56 status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG.
  57
  58 =back
  59
  60 If the SCT is of an unsupported version (only v1 is currently supported), the
  61 validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION.
  62
  63 If the SCT's signature is incorrect, its timestamp is in the future (relative to
  64 the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation
  65 status will be SCT_VALIDATION_STATUS_INVALID.
  66
  67 If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID.
  68
  69 =head1 NOTES
  70
  71 A return value of 0 from SCT_LIST_validate() should not be interpreted as a
  72 failure. At a minimum, only one valid SCT may provide sufficient confidence
  73 that a certificate has been publicly logged.
  74
  75 =head1 RETURN VALUES
  76
  77 SCT_validate() returns a negative integer if an internal error occurs, 0 if the
  78 SCT fails validation, or 1 if the SCT passes validation.
  79
  80 SCT_LIST_validate() returns a negative integer if an internal error occurs, 0
  81 if any of SCTs fails validation, or 1 if they all pass validation.
  82
  83 SCT_get_validation_status() returns the validation status of the SCT.
  84 If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the
  85 returned value will be SCT_VALIDATION_STATUS_NOT_SET.
  86
  87 =head1 SEE ALSO
  88
  89 L<ct(7)>
  90
  91 =head1 HISTORY
  92
  93 These functions were added in OpenSSL 1.1.0.
  94
  95 =head1 COPYRIGHT
  96
  97 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
  98
  99 Licensed under the OpenSSL license (the "License").  You may not use
 100 this file except in compliance with the License.  You can obtain a copy
 101 in the file LICENSE in the source distribution or at
 102 L<https://www.openssl.org/source/license.html>.
 103
 104 =cut