]>
Commit | Line | Data |
---|---|---|
56f3f714 RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d8652be0 | 5 | CT_POLICY_EVAL_CTX_new_ex, |
cb8145ff | 6 | CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, |
ea4b7ded RP |
7 | CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, |
8 | CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, | |
1fa9ffd9 RP |
9 | CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, |
10 | CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - | |
56f3f714 RP |
11 | Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | #include <openssl/ct.h> | |
16 | ||
b4250010 | 17 | CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new_ex(OSSL_LIB_CTX *libctx, |
d8652be0 | 18 | const char *propq); |
56f3f714 RP |
19 | CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); |
20 | void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); | |
21 | X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); | |
ea4b7ded | 22 | int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); |
56f3f714 | 23 | X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); |
ea4b7ded | 24 | int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); |
56f3f714 | 25 | const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); |
e9b77246 BB |
26 | void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, |
27 | CTLOG_STORE *log_store); | |
1fa9ffd9 RP |
28 | uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); |
29 | void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); | |
56f3f714 RP |
30 | |
31 | =head1 DESCRIPTION | |
32 | ||
33 | A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed | |
34 | Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. | |
35 | This policy may be, for example, that at least one valid SCT is available. To | |
1fa9ffd9 RP |
36 | determine this, an SCT's timestamp and signature must be verified. |
37 | This requires: | |
56f3f714 | 38 | |
2f61bc2e | 39 | =over 2 |
56f3f714 | 40 | |
2f61bc2e | 41 | =item * |
56f3f714 | 42 | |
2f61bc2e | 43 | the public key of the log that issued the SCT |
56f3f714 | 44 | |
2f61bc2e | 45 | =item * |
56f3f714 | 46 | |
2f61bc2e RS |
47 | the certificate that the SCT was issued for |
48 | ||
49 | =item * | |
50 | ||
51 | the issuer certificate (if the SCT was issued for a pre-certificate) | |
52 | ||
53 | =item * | |
54 | ||
55 | the current time | |
1fa9ffd9 | 56 | |
56f3f714 RP |
57 | =back |
58 | ||
59 | The above requirements are met using the setters described below. | |
60 | ||
d8652be0 | 61 | CT_POLICY_EVAL_CTX_new_ex() creates an empty policy evaluation context |
aa233ef7 MC |
62 | and associates it with the given library context I<libctx> and property query |
63 | string I<propq>. | |
64 | ||
65 | CT_POLICY_EVAL_CTX_new() does the same thing as | |
d8652be0 | 66 | CT_POLICY_EVAL_CTX_new_ex() except that it uses the default library |
aa233ef7 MC |
67 | context and property query string. |
68 | ||
69 | The CT_POLICY_EVAL_CTX should then be populated using: | |
56f3f714 | 70 | |
2f61bc2e | 71 | =over 2 |
56f3f714 | 72 | |
2f61bc2e RS |
73 | =item * |
74 | ||
75 | CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for | |
56f3f714 | 76 | |
ea4b7ded | 77 | Increments the reference count of the certificate. |
56f3f714 | 78 | |
2f61bc2e RS |
79 | =item * |
80 | ||
81 | CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate | |
ea4b7ded RP |
82 | |
83 | Increments the reference count of the certificate. | |
84 | ||
2f61bc2e RS |
85 | =item * |
86 | ||
87 | CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs | |
ea4b7ded RP |
88 | |
89 | Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the | |
90 | CT_POLICY_EVAL_CTX. | |
56f3f714 | 91 | |
2f61bc2e RS |
92 | =item * |
93 | ||
94 | CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid | |
1fa9ffd9 RP |
95 | |
96 | The SCT timestamp will be compared to this time to check whether the SCT was | |
1871a5aa | 97 | issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose |
c22aa33e RP |
98 | timestamp is in the future". By default, this will be set to 5 minutes in the |
99 | future (e.g. (time() + 300) * 1000), to allow for clock drift. | |
1871a5aa | 100 | |
9c0586d5 | 101 | The time should be in milliseconds since the Unix Epoch. |
1fa9ffd9 | 102 | |
56f3f714 RP |
103 | =back |
104 | ||
56f3f714 | 105 | Each setter has a matching getter for accessing the current value. |
56f3f714 RP |
106 | |
107 | When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to | |
8b12a3e7 | 108 | CT_POLICY_EVAL_CTX_free() to delete it. |
56f3f714 RP |
109 | |
110 | =head1 NOTES | |
111 | ||
112 | The issuer certificate only needs to be provided if at least one of the SCTs | |
113 | was issued for a pre-certificate. This will be the case for SCTs embedded in a | |
114 | certificate (i.e. those in an X.509 extension), but may not be the case for SCTs | |
115 | found in the TLS SCT extension or OCSP response. | |
116 | ||
117 | =head1 RETURN VALUES | |
118 | ||
d8652be0 | 119 | CT_POLICY_EVAL_CTX_new_ex() and CT_POLICY_EVAL_CTX_new() will return |
aa233ef7 | 120 | NULL if malloc fails. |
56f3f714 RP |
121 | |
122 | =head1 SEE ALSO | |
123 | ||
b97fdb57 | 124 | L<ct(7)> |
56f3f714 | 125 | |
32fa3da8 RP |
126 | =head1 HISTORY |
127 | ||
d8652be0 | 128 | CT_POLICY_EVAL_CTX_new_ex was added in OpenSSL 3.0. All other |
aa233ef7 | 129 | functions were added in OpenSSL 1.1.0. |
32fa3da8 | 130 | |
56f3f714 RP |
131 | =head1 COPYRIGHT |
132 | ||
33388b44 | 133 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
56f3f714 | 134 | |
4746f25a | 135 | Licensed under the Apache License 2.0 (the "License"). You may not use |
56f3f714 RP |
136 | this file except in compliance with the License. You can obtain a copy |
137 | in the file LICENSE in the source distribution or at | |
138 | L<https://www.openssl.org/source/license.html>. | |
139 | ||
6c3e9a71 | 140 | =cut |