1 /* 2 * Copyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the Apache License 2.0 (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 OPENSSL_STORE_H 11 # define OPENSSL_STORE_H 12 # pragma once 13 14 # include <openssl/macros.h> 15 # ifndef OPENSSL_NO_DEPRECATED_3_0 16 # define HEADER_OSSL_STORE_H 17 # endif 18 19 # include <stdarg.h> 20 # include <openssl/types.h> 21 # include <openssl/pem.h> 22 # include <openssl/storeerr.h> 23 24 # ifdef __cplusplus 25 extern "C" { 26 # endif 27 28 /*- 29 * The main OSSL_STORE functions. 30 * ------------------------------ 31 * 32 * These allow applications to open a channel to a resource with supported 33 * data (keys, certs, crls, ...), read the data a piece at a time and decide 34 * what to do with it, and finally close. 35 */ 36 37 typedef struct ossl_store_ctx_st OSSL_STORE_CTX; 38 39 /* 40 * Typedef for the OSSL_STORE_INFO post processing callback. This can be used 41 * to massage the given OSSL_STORE_INFO, or to drop it entirely (by returning 42 * NULL). 43 */ 44 typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *, 45 void *); 46 47 /* 48 * Open a channel given a URI. The given UI method will be used any time the 49 * loader needs extra input, for example when a password or pin is needed, and 50 * will be passed the same user data every time it's needed in this context. 51 * 52 * Returns a context reference which represents the channel to communicate 53 * through. 54 */ 55 OSSL_STORE_CTX * 56 OSSL_STORE_open(const char *uri, const UI_METHOD *ui_method, void *ui_data, 57 OSSL_STORE_post_process_info_fn post_process, 58 void *post_process_data); 59 OSSL_STORE_CTX * 60 OSSL_STORE_open_ex(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, 61 const UI_METHOD *ui_method, void *ui_data, 62 const OSSL_PARAM params[], 63 OSSL_STORE_post_process_info_fn post_process, 64 void *post_process_data); 65 66 /* 67 * Control / fine tune the OSSL_STORE channel. |cmd| determines what is to be 68 * done, and depends on the underlying loader (use OSSL_STORE_get0_scheme to 69 * determine which loader is used), except for common commands (see below). 70 * Each command takes different arguments. 71 */ 72 # ifndef OPENSSL_NO_DEPRECATED_3_0 73 OSSL_DEPRECATEDIN_3_0 int OSSL_STORE_ctrl(OSSL_STORE_CTX *ctx, int cmd, 74 ... /* args */); 75 OSSL_DEPRECATEDIN_3_0 int OSSL_STORE_vctrl(OSSL_STORE_CTX *ctx, int cmd, 76 va_list args); 77 # endif 78 79 # ifndef OPENSSL_NO_DEPRECATED_3_0 80 81 /* 82 * Common ctrl commands that different loaders may choose to support. 83 */ 84 /* int on = 0 or 1; STORE_ctrl(ctx, STORE_C_USE_SECMEM, &on); */ 85 # define OSSL_STORE_C_USE_SECMEM 1 86 /* Where custom commands start */ 87 # define OSSL_STORE_C_CUSTOM_START 100 88 89 # endif 90 91 /* 92 * Read one data item (a key, a cert, a CRL) that is supported by the OSSL_STORE 93 * functionality, given a context. 94 * Returns a OSSL_STORE_INFO pointer, from which OpenSSL typed data can be 95 * extracted with OSSL_STORE_INFO_get0_PKEY(), OSSL_STORE_INFO_get0_CERT(), ... 96 * NULL is returned on error, which may include that the data found at the URI 97 * can't be figured out for certain or is ambiguous. 98 */ 99 OSSL_STORE_INFO *OSSL_STORE_load(OSSL_STORE_CTX *ctx); 100 101 /* 102 * Check if end of data (end of file) is reached 103 * Returns 1 on end, 0 otherwise. 104 */ 105 int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); 106 107 /* 108 * Check if an error occurred 109 * Returns 1 if it did, 0 otherwise. 110 */ 111 int OSSL_STORE_error(OSSL_STORE_CTX *ctx); 112 113 /* 114 * Close the channel 115 * Returns 1 on success, 0 on error. 116 */ 117 int OSSL_STORE_close(OSSL_STORE_CTX *ctx); 118 119 /* 120 * Attach to a BIO. This works like OSSL_STORE_open() except it takes a 121 * BIO instead of a uri, along with a scheme to use when reading. 122 * The given UI method will be used any time the loader needs extra input, 123 * for example when a password or pin is needed, and will be passed the 124 * same user data every time it's needed in this context. 125 * 126 * Returns a context reference which represents the channel to communicate 127 * through. 128 * 129 * Note that this function is considered unsafe, all depending on what the 130 * BIO actually reads. 131 */ 132 OSSL_STORE_CTX *OSSL_STORE_attach(BIO *bio, const char *scheme, 133 OSSL_LIB_CTX *libctx, const char *propq, 134 const UI_METHOD *ui_method, void *ui_data, 135 const OSSL_PARAM params[], 136 OSSL_STORE_post_process_info_fn post_process, 137 void *post_process_data); 138 139 /*- 140 * Extracting OpenSSL types from and creating new OSSL_STORE_INFOs 141 * --------------------------------------------------------------- 142 */ 143 144 /* 145 * Types of data that can be ossl_stored in a OSSL_STORE_INFO. 146 * OSSL_STORE_INFO_NAME is typically found when getting a listing of 147 * available "files" / "tokens" / what have you. 148 */ 149 # define OSSL_STORE_INFO_NAME 1 /* char * */ 150 # define OSSL_STORE_INFO_PARAMS 2 /* EVP_PKEY * */ 151 # define OSSL_STORE_INFO_PUBKEY 3 /* EVP_PKEY * */ 152 # define OSSL_STORE_INFO_PKEY 4 /* EVP_PKEY * */ 153 # define OSSL_STORE_INFO_CERT 5 /* X509 * */ 154 # define OSSL_STORE_INFO_CRL 6 /* X509_CRL * */ 155 156 /* 157 * Functions to generate OSSL_STORE_INFOs, one function for each type we 158 * support having in them, as well as a generic constructor. 159 * 160 * In all cases, ownership of the object is transferred to the OSSL_STORE_INFO 161 * and will therefore be freed when the OSSL_STORE_INFO is freed. 162 */ 163 OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data); 164 OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); 165 int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); 166 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(EVP_PKEY *params); 167 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey); 168 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); 169 OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); 170 OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); 171 172 /* 173 * Functions to try to extract data from a OSSL_STORE_INFO. 174 */ 175 int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *info); 176 void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info); 177 const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *info); 178 char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *info); 179 const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO *info); 180 char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *info); 181 EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *info); 182 EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *info); 183 EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info); 184 EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info); 185 EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *info); 186 EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *info); 187 X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *info); 188 X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *info); 189 X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *info); 190 X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *info); 191 192 const char *OSSL_STORE_INFO_type_string(int type); 193 194 /* 195 * Free the OSSL_STORE_INFO 196 */ 197 void OSSL_STORE_INFO_free(OSSL_STORE_INFO *info); 198 199 200 /*- 201 * Functions to construct a search URI from a base URI and search criteria 202 * ----------------------------------------------------------------------- 203 */ 204 205 /* OSSL_STORE search types */ 206 # define OSSL_STORE_SEARCH_BY_NAME 1 /* subject in certs, issuer in CRLs */ 207 # define OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 2 208 # define OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 3 209 # define OSSL_STORE_SEARCH_BY_ALIAS 4 210 211 /* To check what search types the scheme handler supports */ 212 int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int search_type); 213 214 /* Search term constructors */ 215 /* 216 * The input is considered to be owned by the caller, and must therefore 217 * remain present throughout the lifetime of the returned OSSL_STORE_SEARCH 218 */ 219 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name); 220 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name, 221 const ASN1_INTEGER 222 *serial); 223 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest, 224 const unsigned char 225 *bytes, size_t len); 226 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias); 227 228 /* Search term destructor */ 229 void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search); 230 231 /* Search term accessors */ 232 int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion); 233 X509_NAME *OSSL_STORE_SEARCH_get0_name(const OSSL_STORE_SEARCH *criterion); 234 const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH 235 *criterion); 236 const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH 237 *criterion, size_t *length); 238 const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion); 239 const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH *criterion); 240 241 /* 242 * Add search criterion and expected return type (which can be unspecified) 243 * to the loading channel. This MUST happen before the first OSSL_STORE_load(). 244 */ 245 int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); 246 int OSSL_STORE_find(OSSL_STORE_CTX *ctx, const OSSL_STORE_SEARCH *search); 247 248 249 /*- 250 * Function to fetch a loader and extract data from it 251 * --------------------------------------------------- 252 */ 253 254 typedef struct ossl_store_loader_st OSSL_STORE_LOADER; 255 256 OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx, 257 const char *scheme, 258 const char *properties); 259 int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader); 260 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); 261 const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER * 262 loader); 263 const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader); 264 const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader); 265 int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader, 266 const char *scheme); 267 void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx, 268 void (*fn)(OSSL_STORE_LOADER *loader, 269 void *arg), 270 void *arg); 271 int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader, 272 void (*fn)(const char *name, void *data), 273 void *data); 274 275 /*- 276 * Function to register a loader for the given URI scheme. 277 * ------------------------------------------------------- 278 * 279 * The loader receives all the main components of an URI except for the 280 * scheme. 281 */ 282 283 # ifndef OPENSSL_NO_DEPRECATED_3_0 284 285 /* struct ossl_store_loader_ctx_st is defined differently by each loader */ 286 typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; 287 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn) 288 (const OSSL_STORE_LOADER *loader, const char *uri, 289 const UI_METHOD *ui_method, void *ui_data); 290 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn) 291 (const OSSL_STORE_LOADER *loader, 292 const char *uri, OSSL_LIB_CTX *libctx, const char *propq, 293 const UI_METHOD *ui_method, void *ui_data); 294 295 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn) 296 (const OSSL_STORE_LOADER *loader, BIO *bio, 297 OSSL_LIB_CTX *libctx, const char *propq, 298 const UI_METHOD *ui_method, void *ui_data); 299 typedef int (*OSSL_STORE_ctrl_fn) 300 (OSSL_STORE_LOADER_CTX *ctx, int cmd, va_list args); 301 typedef int (*OSSL_STORE_expect_fn) 302 (OSSL_STORE_LOADER_CTX *ctx, int expected); 303 typedef int (*OSSL_STORE_find_fn) 304 (OSSL_STORE_LOADER_CTX *ctx, const OSSL_STORE_SEARCH *criteria); 305 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn) 306 (OSSL_STORE_LOADER_CTX *ctx, const UI_METHOD *ui_method, void *ui_data); 307 typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); 308 typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); 309 typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); 310 311 # endif 312 # ifndef OPENSSL_NO_DEPRECATED_3_0 313 OSSL_DEPRECATEDIN_3_0 314 OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); 315 OSSL_DEPRECATEDIN_3_0 316 int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *loader, 317 OSSL_STORE_open_fn open_function); 318 OSSL_DEPRECATEDIN_3_0 319 int OSSL_STORE_LOADER_set_open_ex(OSSL_STORE_LOADER *loader, 320 OSSL_STORE_open_ex_fn open_ex_function); 321 OSSL_DEPRECATEDIN_3_0 322 int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader, 323 OSSL_STORE_attach_fn attach_function); 324 OSSL_DEPRECATEDIN_3_0 325 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *loader, 326 OSSL_STORE_ctrl_fn ctrl_function); 327 OSSL_DEPRECATEDIN_3_0 328 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader, 329 OSSL_STORE_expect_fn expect_function); 330 OSSL_DEPRECATEDIN_3_0 331 int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader, 332 OSSL_STORE_find_fn find_function); 333 OSSL_DEPRECATEDIN_3_0 334 int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *loader, 335 OSSL_STORE_load_fn load_function); 336 OSSL_DEPRECATEDIN_3_0 337 int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *loader, 338 OSSL_STORE_eof_fn eof_function); 339 OSSL_DEPRECATEDIN_3_0 340 int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *loader, 341 OSSL_STORE_error_fn error_function); 342 OSSL_DEPRECATEDIN_3_0 343 int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *loader, 344 OSSL_STORE_close_fn close_function); 345 OSSL_DEPRECATEDIN_3_0 346 const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER *loader); 347 OSSL_DEPRECATEDIN_3_0 348 const char * OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER *loader); 349 OSSL_DEPRECATEDIN_3_0 350 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); 351 OSSL_DEPRECATEDIN_3_0 352 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); 353 # endif 354 355 /*- 356 * Functions to list STORE loaders 357 * ------------------------------- 358 */ 359 # ifndef OPENSSL_NO_DEPRECATED_3_0 360 OSSL_DEPRECATEDIN_3_0 361 int OSSL_STORE_do_all_loaders(void (*do_function)(const OSSL_STORE_LOADER *loader, 362 void *do_arg), 363 void *do_arg); 364 # endif 365 366 # ifdef __cplusplus 367 } 368 # endif 369 #endif 370