]>
Commit | Line | Data |
---|---|---|
56f3f714 RP |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
d8652be0 | 5 | CTLOG_STORE_new_ex, |
56f3f714 RP |
6 | CTLOG_STORE_new, CTLOG_STORE_free, |
7 | CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - | |
8 | Create and populate a Certificate Transparency log list | |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/ct.h> | |
13 | ||
b4250010 | 14 | CTLOG_STORE *CTLOG_STORE_new_ex(OSSL_LIB_CTX *libctx, const char *propq); |
56f3f714 RP |
15 | CTLOG_STORE *CTLOG_STORE_new(void); |
16 | void CTLOG_STORE_free(CTLOG_STORE *store); | |
17 | ||
18 | int CTLOG_STORE_load_default_file(CTLOG_STORE *store); | |
19 | int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file); | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency | |
24 | logs). The list can be loaded from one or more files and then searched by LogID | |
25 | (see RFC 6962, Section 3.2, for the definition of a LogID). | |
26 | ||
d8652be0 | 27 | CTLOG_STORE_new_ex() creates an empty list of CT logs associated with |
aa233ef7 MC |
28 | the library context I<libctx> and the property query string I<propq>. |
29 | ||
d8652be0 | 30 | CTLOG_STORE_new() does the same thing as CTLOG_STORE_new_ex() but with |
aa233ef7 MC |
31 | the default library context and property query string. |
32 | ||
33 | The CTLOG_STORE is then populated by CTLOG_STORE_load_default_file() or | |
34 | CTLOG_STORE_load_file(). CTLOG_STORE_load_default_file() loads from the default | |
35 | file, which is named F<ct_log_list.cnf> in OPENSSLDIR (see the output of | |
36 | L<openssl-version(1)>). This can be overridden using an environment variable | |
37 | named B<CTLOG_FILE>. CTLOG_STORE_load_file() loads from a caller-specified file | |
38 | path instead. Both of these functions append any loaded CT logs to the | |
39 | CTLOG_STORE. | |
56f3f714 RP |
40 | |
41 | The expected format of the file is: | |
42 | ||
43 | enabled_logs=foo,bar | |
44 | ||
45 | [foo] | |
46 | description = Log 1 | |
882babda | 47 | key = <base64-encoded DER SubjectPublicKeyInfo here> |
56f3f714 RP |
48 | |
49 | [bar] | |
50 | description = Log 2 | |
882babda | 51 | key = <base64-encoded DER SubjectPublicKeyInfo here> |
56f3f714 RP |
52 | |
53 | Once a CTLOG_STORE is no longer required, it should be passed to | |
8b12a3e7 | 54 | CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along |
56f3f714 RP |
55 | with the CTLOG_STORE itself. |
56 | ||
57 | =head1 NOTES | |
58 | ||
59 | If there are any invalid CT logs in a file, they are skipped and the remaining | |
60 | valid logs will still be added to the CTLOG_STORE. A CT log will be considered | |
61 | invalid if it is missing a "key" or "description" field. | |
62 | ||
63 | =head1 RETURN VALUES | |
64 | ||
65 | Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if | |
66 | all CT logs in the file are successfully parsed and loaded, 0 otherwise. | |
67 | ||
68 | =head1 SEE ALSO | |
69 | ||
b97fdb57 | 70 | L<ct(7)>, |
56f3f714 RP |
71 | L<CTLOG_STORE_get0_log_by_id(3)>, |
72 | L<SSL_CTX_set_ctlog_list_file(3)> | |
73 | ||
32fa3da8 RP |
74 | =head1 HISTORY |
75 | ||
d8652be0 | 76 | CTLOG_STORE_new_ex was added in OpenSSL 3.0. All other functions were |
aa233ef7 | 77 | added in OpenSSL 1.1.0. |
32fa3da8 | 78 | |
56f3f714 RP |
79 | =head1 COPYRIGHT |
80 | ||
33388b44 | 81 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
56f3f714 | 82 | |
4746f25a | 83 | Licensed under the Apache License 2.0 (the "License"). You may not use |
56f3f714 RP |
84 | this file except in compliance with the License. You can obtain a copy |
85 | in the file LICENSE in the source distribution or at | |
86 | L<https://www.openssl.org/source/license.html>. | |
87 | ||
6c3e9a71 | 88 | =cut |