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