]>
Commit | Line | Data |
---|---|---|
56f3f714 RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
cb8145ff | 5 | CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, |
ea4b7ded RP |
6 | CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, |
7 | CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, | |
1fa9ffd9 RP |
8 | CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, |
9 | CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - | |
56f3f714 RP |
10 | Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/ct.h> | |
15 | ||
16 | CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); | |
17 | void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); | |
18 | X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); | |
ea4b7ded | 19 | int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); |
56f3f714 | 20 | X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); |
ea4b7ded | 21 | int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); |
56f3f714 | 22 | const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); |
ea4b7ded | 23 | void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store); |
1fa9ffd9 RP |
24 | uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); |
25 | void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); | |
56f3f714 RP |
26 | |
27 | =head1 DESCRIPTION | |
28 | ||
29 | A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed | |
30 | Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. | |
31 | This policy may be, for example, that at least one valid SCT is available. To | |
1fa9ffd9 RP |
32 | determine this, an SCT's timestamp and signature must be verified. |
33 | This requires: | |
56f3f714 RP |
34 | |
35 | =over | |
36 | ||
37 | =item * the public key of the log that issued the SCT | |
38 | ||
39 | =item * the certificate that the SCT was issued for | |
40 | ||
41 | =item * the issuer certificate (if the SCT was issued for a pre-certificate) | |
42 | ||
1fa9ffd9 RP |
43 | =item * the current time |
44 | ||
56f3f714 RP |
45 | =back |
46 | ||
47 | The above requirements are met using the setters described below. | |
48 | ||
8b12a3e7 | 49 | CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This |
56f3f714 RP |
50 | should then be populated using: |
51 | ||
52 | =over | |
53 | ||
ea4b7ded | 54 | =item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for |
56f3f714 | 55 | |
ea4b7ded | 56 | Increments the reference count of the certificate. |
56f3f714 | 57 | |
ea4b7ded RP |
58 | =item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate |
59 | ||
60 | Increments the reference count of the certificate. | |
61 | ||
62 | =item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs | |
63 | ||
64 | Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the | |
65 | CT_POLICY_EVAL_CTX. | |
56f3f714 | 66 | |
1fa9ffd9 RP |
67 | =item * CT_POLICY_EVAL_CTX_set_time() to provide the current time |
68 | ||
69 | The SCT timestamp will be compared to this time to check whether the SCT was | |
70 | supposedly issued in the future. RFC6962 states that "TLS clients MUST reject | |
71 | SCTs whose timestamp is in the future". | |
72 | ||
56f3f714 RP |
73 | =back |
74 | ||
56f3f714 | 75 | Each setter has a matching getter for accessing the current value. |
56f3f714 RP |
76 | |
77 | When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to | |
8b12a3e7 | 78 | CT_POLICY_EVAL_CTX_free() to delete it. |
56f3f714 RP |
79 | |
80 | =head1 NOTES | |
81 | ||
82 | The issuer certificate only needs to be provided if at least one of the SCTs | |
83 | was issued for a pre-certificate. This will be the case for SCTs embedded in a | |
84 | certificate (i.e. those in an X.509 extension), but may not be the case for SCTs | |
85 | found in the TLS SCT extension or OCSP response. | |
86 | ||
87 | =head1 RETURN VALUES | |
88 | ||
8b12a3e7 | 89 | CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. |
56f3f714 RP |
90 | |
91 | =head1 SEE ALSO | |
92 | ||
b97fdb57 | 93 | L<ct(7)> |
56f3f714 | 94 | |
32fa3da8 RP |
95 | =head1 HISTORY |
96 | ||
97 | These functions were added in OpenSSL 1.1.0. | |
98 | ||
56f3f714 RP |
99 | =head1 COPYRIGHT |
100 | ||
101 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
102 | ||
103 | Licensed under the OpenSSL license (the "License"). You may not use | |
104 | this file except in compliance with the License. You can obtain a copy | |
105 | in the file LICENSE in the source distribution or at | |
106 | L<https://www.openssl.org/source/license.html>. | |
107 | ||
6c3e9a71 | 108 | =cut |