]>
Commit | Line | Data |
---|---|---|
71a5516d | 1 | /* |
6738bf14 | 2 | * Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved. |
71a5516d RL |
3 | * |
4 | * Licensed under the OpenSSL license (the "License"). You may not use | |
5 | * this file except in compliance with the License. You can obtain a copy | |
6 | * in the file LICENSE in the source distribution or at | |
7 | * https://www.openssl.org/source/license.html | |
8 | */ | |
9 | ||
10 | #ifndef HEADER_OSSL_STORE_H | |
11 | # define HEADER_OSSL_STORE_H | |
12 | ||
13 | # include <stdarg.h> | |
14 | # include <openssl/ossl_typ.h> | |
15 | # include <openssl/pem.h> | |
16 | # include <openssl/storeerr.h> | |
17 | ||
18 | # ifdef __cplusplus | |
19 | extern "C" { | |
20 | # endif | |
21 | ||
22 | /*- | |
23 | * The main OSSL_STORE functions. | |
24 | * ------------------------------ | |
25 | * | |
26 | * These allow applications to open a channel to a resource with supported | |
27 | * data (keys, certs, crls, ...), read the data a piece at a time and decide | |
28 | * what to do with it, and finally close. | |
29 | */ | |
30 | ||
31 | typedef struct ossl_store_ctx_st OSSL_STORE_CTX; | |
32 | ||
33 | /* | |
34 | * Typedef for the OSSL_STORE_INFO post processing callback. This can be used | |
35 | * to massage the given OSSL_STORE_INFO, or to drop it entirely (by returning | |
36 | * NULL). | |
37 | */ | |
38 | typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, | |
39 | void *); | |
40 | ||
41 | /* | |
42 | * Open a channel given a URI. The given UI method will be used any time the | |
43 | * loader needs extra input, for example when a password or pin is needed, and | |
44 | * will be passed the same user data every time it's needed in this context. | |
45 | * | |
46 | * Returns a context reference which represents the channel to communicate | |
47 | * through. | |
48 | */ | |
49 | OSSL_STORE_CTX *OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, | |
50 | void *ui_data, | |
51 | OSSL_STORE_post_process_info_fn post_process, | |
52 | void *post_process_data); | |
53 | ||
54 | /* | |
55 | * Control / fine tune the OSSL_STORE channel. |cmd| determines what is to be | |
56 | * done, and depends on the underlying loader (use OSSL_STORE_get0_scheme to | |
57 | * determine which loader is used), except for common commands (see below). | |
58 | * Each command takes different arguments. | |
59 | */ | |
60 | int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, ... /* args */); | |
4fd39122 | 61 | int OSSL_STORE_vctrl(OSSL_STORE_CTX *ctx, int cmd, va_list args); |
71a5516d RL |
62 | |
63 | /* | |
64 | * Common ctrl commands that different loaders may choose to support. | |
65 | */ | |
7852f588 RL |
66 | /* int on = 0 or 1; STORE_ctrl(ctx, STORE_C_USE_SECMEM, &on); */ |
67 | # define OSSL_STORE_C_USE_SECMEM 1 | |
71a5516d RL |
68 | /* Where custom commands start */ |
69 | # define OSSL_STORE_C_CUSTOM_START 100 | |
70 | ||
71 | /* | |
72 | * Read one data item (a key, a cert, a CRL) that is supported by the OSSL_STORE | |
73 | * functionality, given a context. | |
74 | * Returns a OSSL_STORE_INFO pointer, from which OpenSSL typed data can be | |
75 | * extracted with OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(), ... | |
76 | * NULL is returned on error, which may include that the data found at the URI | |
77 | * can't be figured out for certain or is ambiguous. | |
78 | */ | |
79 | OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); | |
80 | ||
81 | /* | |
82 | * Check if end of data (end of file) is reached | |
83 | * Returns 1 on end, 0 otherwise. | |
84 | */ | |
85 | int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); | |
86 | ||
87 | /* | |
88 | * Check if an error occured | |
89 | * Returns 1 if it did, 0 otherwise. | |
90 | */ | |
91 | int OSSL_STORE_error(OSSL_STORE_CTX *ctx); | |
92 | ||
93 | /* | |
94 | * Close the channel | |
95 | * Returns 1 on success, 0 on error. | |
96 | */ | |
97 | int OSSL_STORE_close(OSSL_STORE_CTX *ctx); | |
98 | ||
99 | ||
100 | /*- | |
101 | * Extracting OpenSSL types from and creating new OSSL_STORE_INFOs | |
102 | * --------------------------------------------------------------- | |
103 | */ | |
104 | ||
105 | /* | |
106 | * Types of data that can be ossl_stored in a OSSL_STORE_INFO. | |
107 | * OSSL_STORE_INFO_NAME is typically found when getting a listing of | |
108 | * available "files" / "tokens" / what have you. | |
109 | */ | |
110 | # define OSSL_STORE_INFO_NAME 1 /* char * */ | |
111 | # define OSSL_STORE_INFO_PARAMS 2 /* EVP_PKEY * */ | |
112 | # define OSSL_STORE_INFO_PKEY 3 /* EVP_PKEY * */ | |
113 | # define OSSL_STORE_INFO_CERT 4 /* X509 * */ | |
114 | # define OSSL_STORE_INFO_CRL 5 /* X509_CRL * */ | |
115 | ||
116 | /* | |
117 | * Functions to generate OSSL_STORE_INFOs, one function for each type we | |
1fb2993d | 118 | * support having in them, as well as a generic constructor. |
71a5516d RL |
119 | * |
120 | * In all cases, ownership of the object is transfered to the OSSL_STORE_INFO | |
121 | * and will therefore be freed when the OSSL_STORE_INFO is freed. | |
122 | */ | |
123 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); | |
124 | int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); | |
125 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(EVP_PKEY *params); | |
126 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); | |
127 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); | |
128 | OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); | |
129 | ||
130 | /* | |
131 | * Functions to try to extract data from a OSSL_STORE_INFO. | |
132 | */ | |
133 | int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *info); | |
134 | const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *info); | |
135 | char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *info); | |
136 | const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO *info); | |
137 | char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *info); | |
138 | EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *info); | |
139 | EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *info); | |
140 | EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *info); | |
141 | EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *info); | |
142 | X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *info); | |
143 | X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *info); | |
144 | X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *info); | |
145 | X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *info); | |
146 | ||
147 | const char *OSSL_STORE_INFO_type_string(int type); | |
148 | ||
149 | /* | |
150 | * Free the OSSL_STORE_INFO | |
151 | */ | |
152 | void OSSL_STORE_INFO_free(OSSL_STORE_INFO *info); | |
153 | ||
154 | ||
155 | /*- | |
156 | * Function to register a loader for the given URI scheme. | |
157 | * ------------------------------------------------------- | |
158 | * | |
159 | * The loader receives all the main components of an URI except for the | |
160 | * scheme. | |
161 | */ | |
162 | ||
163 | typedef struct ossl_store_loader_st OSSL_STORE_LOADER; | |
f91ded1f RL |
164 | OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); |
165 | const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER *loader); | |
71a5516d RL |
166 | const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER *loader); |
167 | /* struct ossl_store_loader_ctx_st is defined differently by each loader */ | |
168 | typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; | |
169 | typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn)(const OSSL_STORE_LOADER | |
170 | *loader, | |
171 | const char *uri, | |
172 | const UI_METHOD *ui_method, | |
173 | void *ui_data); | |
174 | int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *loader, | |
175 | OSSL_STORE_open_fn open_function); | |
176 | typedef int (*OSSL_STORE_ctrl_fn)(OSSL_STORE_LOADER_CTX *ctx, int cmd, | |
177 | va_list args); | |
178 | int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *loader, | |
179 | OSSL_STORE_ctrl_fn ctrl_function); | |
180 | typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx, | |
181 | const UI_METHOD *ui_method, | |
182 | void *ui_data); | |
183 | int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *loader, | |
184 | OSSL_STORE_load_fn load_function); | |
185 | typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
186 | int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *loader, | |
187 | OSSL_STORE_eof_fn eof_function); | |
188 | typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
189 | int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *loader, | |
190 | OSSL_STORE_error_fn error_function); | |
191 | typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); | |
192 | int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *loader, | |
193 | OSSL_STORE_close_fn close_function); | |
194 | void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); | |
195 | ||
196 | int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); | |
197 | OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); | |
198 | ||
f91ded1f RL |
199 | /*- |
200 | * Functions to list STORE loaders | |
201 | * ------------------------------- | |
202 | */ | |
203 | int OSSL_STORE_do_all_loaders(void (*do_function) (const OSSL_STORE_LOADER | |
204 | *loader, void *do_arg), | |
205 | void *do_arg); | |
206 | ||
71a5516d RL |
207 | # ifdef __cplusplus |
208 | } | |
209 | # endif | |
210 | #endif |