]>
Commit | Line | Data |
---|---|---|
56f3f714 RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SCT_validate, SCT_LIST_validate, SCT_get_validation_status - | |
a0a9f36e | 6 | checks Signed Certificate Timestamps (SCTs) are valid |
56f3f714 RP |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/ct.h> | |
11 | ||
ae97a654 | 12 | typedef enum { |
2947af32 BB |
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 | |
ae97a654 RP |
19 | } sct_validation_status_t; |
20 | ||
56f3f714 RP |
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); | |
a0a9f36e | 23 | sct_validation_status_t SCT_get_validation_status(const SCT *sct); |
56f3f714 RP |
24 | |
25 | =head1 DESCRIPTION | |
26 | ||
a0a9f36e RP |
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(). | |
56f3f714 | 31 | |
a0a9f36e | 32 | A CT_POLICY_EVAL_CTX must be provided that specifies: |
56f3f714 | 33 | |
2f61bc2e | 34 | =over 2 |
a0a9f36e | 35 | |
2f61bc2e RS |
36 | =item * |
37 | ||
38 | The certificate the SCT was issued for. | |
a0a9f36e RP |
39 | |
40 | Failure to provide the certificate will result in the validation status being | |
41 | SCT_VALIDATION_STATUS_UNVERIFIED. | |
42 | ||
2f61bc2e RS |
43 | =item * |
44 | ||
45 | The issuer of that certificate. | |
a0a9f36e RP |
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. | |
56f3f714 | 50 | |
2f61bc2e RS |
51 | =item * |
52 | ||
53 | A CTLOG_STORE that contains the CT log that issued this SCT. | |
56f3f714 | 54 | |
a0a9f36e RP |
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 | ||
1fa9ffd9 RP |
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. | |
a0a9f36e RP |
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. | |
56f3f714 RP |
74 | |
75 | =head1 RETURN VALUES | |
76 | ||
a0a9f36e RP |
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. | |
56f3f714 | 82 | |
a0a9f36e RP |
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. | |
56f3f714 RP |
86 | |
87 | =head1 SEE ALSO | |
88 | ||
b97fdb57 | 89 | L<ct(7)> |
56f3f714 | 90 | |
32fa3da8 RP |
91 | =head1 HISTORY |
92 | ||
93 | These functions were added in OpenSSL 1.1.0. | |
94 | ||
56f3f714 RP |
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 | ||
6c3e9a71 | 104 | =cut |