1 /* 2 * Copyright 2016-2023 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 * Deletes the object in the store by URI. 103 * Returns 1 on success, 0 otherwise. 104 */ 105 int OSSL_STORE_delete(const char *uri, OSSL_LIB_CTX *libctx, const char *propq, 106 const UI_METHOD *ui_method, void *ui_data, 107 const OSSL_PARAM params[]); 108 109 /* 110 * Check if end of data (end of file) is reached 111 * Returns 1 on end, 0 otherwise. 112 */ 113 int OSSL_STORE_eof(OSSL_STORE_CTX *ctx); 114 115 /* 116 * Check if an error occurred 117 * Returns 1 if it did, 0 otherwise. 118 */ 119 int OSSL_STORE_error(OSSL_STORE_CTX *ctx); 120 121 /* 122 * Close the channel 123 * Returns 1 on success, 0 on error. 124 */ 125 int OSSL_STORE_close(OSSL_STORE_CTX *ctx); 126 127 /* 128 * Attach to a BIO. This works like OSSL_STORE_open() except it takes a 129 * BIO instead of a uri, along with a scheme to use when reading. 130 * The given UI method will be used any time the loader needs extra input, 131 * for example when a password or pin is needed, and will be passed the 132 * same user data every time it's needed in this context. 133 * 134 * Returns a context reference which represents the channel to communicate 135 * through. 136 * 137 * Note that this function is considered unsafe, all depending on what the 138 * BIO actually reads. 139 */ 140 OSSL_STORE_CTX *OSSL_STORE_attach(BIO *bio, const char *scheme, 141 OSSL_LIB_CTX *libctx, const char *propq, 142 const UI_METHOD *ui_method, void *ui_data, 143 const OSSL_PARAM params[], 144 OSSL_STORE_post_process_info_fn post_process, 145 void *post_process_data); 146 147 /*- 148 * Extracting OpenSSL types from and creating new OSSL_STORE_INFOs 149 * --------------------------------------------------------------- 150 */ 151 152 /* 153 * Types of data that can be ossl_stored in a OSSL_STORE_INFO. 154 * OSSL_STORE_INFO_NAME is typically found when getting a listing of 155 * available "files" / "tokens" / what have you. 156 */ 157 # define OSSL_STORE_INFO_NAME 1 /* char * */ 158 # define OSSL_STORE_INFO_PARAMS 2 /* EVP_PKEY * */ 159 # define OSSL_STORE_INFO_PUBKEY 3 /* EVP_PKEY * */ 160 # define OSSL_STORE_INFO_PKEY 4 /* EVP_PKEY * */ 161 # define OSSL_STORE_INFO_CERT 5 /* X509 * */ 162 # define OSSL_STORE_INFO_CRL 6 /* X509_CRL * */ 163 164 /* 165 * Functions to generate OSSL_STORE_INFOs, one function for each type we 166 * support having in them, as well as a generic constructor. 167 * 168 * In all cases, ownership of the object is transferred to the OSSL_STORE_INFO 169 * and will therefore be freed when the OSSL_STORE_INFO is freed. 170 */ 171 OSSL_STORE_INFO *OSSL_STORE_INFO_new(int type, void *data); 172 OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name); 173 int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc); 174 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(EVP_PKEY *params); 175 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PUBKEY(EVP_PKEY *pubkey); 176 OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey); 177 OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509); 178 OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl); 179 180 /* 181 * Functions to try to extract data from a OSSL_STORE_INFO. 182 */ 183 int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *info); 184 void *OSSL_STORE_INFO_get0_data(int type, const OSSL_STORE_INFO *info); 185 const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *info); 186 char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *info); 187 const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO *info); 188 char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *info); 189 EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *info); 190 EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *info); 191 EVP_PKEY *OSSL_STORE_INFO_get0_PUBKEY(const OSSL_STORE_INFO *info); 192 EVP_PKEY *OSSL_STORE_INFO_get1_PUBKEY(const OSSL_STORE_INFO *info); 193 EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *info); 194 EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *info); 195 X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *info); 196 X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *info); 197 X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *info); 198 X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *info); 199 200 const char *OSSL_STORE_INFO_type_string(int type); 201 202 /* 203 * Free the OSSL_STORE_INFO 204 */ 205 void OSSL_STORE_INFO_free(OSSL_STORE_INFO *info); 206 207 208 /*- 209 * Functions to construct a search URI from a base URI and search criteria 210 * ----------------------------------------------------------------------- 211 */ 212 213 /* OSSL_STORE search types */ 214 # define OSSL_STORE_SEARCH_BY_NAME 1 /* subject in certs, issuer in CRLs */ 215 # define OSSL_STORE_SEARCH_BY_ISSUER_SERIAL 2 216 # define OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT 3 217 # define OSSL_STORE_SEARCH_BY_ALIAS 4 218 219 /* To check what search types the scheme handler supports */ 220 int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int search_type); 221 222 /* Search term constructors */ 223 /* 224 * The input is considered to be owned by the caller, and must therefore 225 * remain present throughout the lifetime of the returned OSSL_STORE_SEARCH 226 */ 227 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name); 228 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name, 229 const ASN1_INTEGER 230 *serial); 231 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest, 232 const unsigned char 233 *bytes, size_t len); 234 OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias); 235 236 /* Search term destructor */ 237 void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search); 238 239 /* Search term accessors */ 240 int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion); 241 X509_NAME *OSSL_STORE_SEARCH_get0_name(const OSSL_STORE_SEARCH *criterion); 242 const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH 243 *criterion); 244 const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH 245 *criterion, size_t *length); 246 const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion); 247 const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH *criterion); 248 249 /* 250 * Add search criterion and expected return type (which can be unspecified) 251 * to the loading channel. This MUST happen before the first OSSL_STORE_load(). 252 */ 253 int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type); 254 int OSSL_STORE_find(OSSL_STORE_CTX *ctx, const OSSL_STORE_SEARCH *search); 255 256 257 /*- 258 * Function to fetch a loader and extract data from it 259 * --------------------------------------------------- 260 */ 261 262 typedef struct ossl_store_loader_st OSSL_STORE_LOADER; 263 264 OSSL_STORE_LOADER *OSSL_STORE_LOADER_fetch(OSSL_LIB_CTX *libctx, 265 const char *scheme, 266 const char *properties); 267 int OSSL_STORE_LOADER_up_ref(OSSL_STORE_LOADER *loader); 268 void OSSL_STORE_LOADER_free(OSSL_STORE_LOADER *loader); 269 const OSSL_PROVIDER *OSSL_STORE_LOADER_get0_provider(const OSSL_STORE_LOADER * 270 loader); 271 const char *OSSL_STORE_LOADER_get0_properties(const OSSL_STORE_LOADER *loader); 272 const char *OSSL_STORE_LOADER_get0_description(const OSSL_STORE_LOADER *loader); 273 int OSSL_STORE_LOADER_is_a(const OSSL_STORE_LOADER *loader, 274 const char *scheme); 275 void OSSL_STORE_LOADER_do_all_provided(OSSL_LIB_CTX *libctx, 276 void (*fn)(OSSL_STORE_LOADER *loader, 277 void *arg), 278 void *arg); 279 int OSSL_STORE_LOADER_names_do_all(const OSSL_STORE_LOADER *loader, 280 void (*fn)(const char *name, void *data), 281 void *data); 282 283 /*- 284 * Function to register a loader for the given URI scheme. 285 * ------------------------------------------------------- 286 * 287 * The loader receives all the main components of an URI except for the 288 * scheme. 289 */ 290 291 # ifndef OPENSSL_NO_DEPRECATED_3_0 292 293 /* struct ossl_store_loader_ctx_st is defined differently by each loader */ 294 typedef struct ossl_store_loader_ctx_st OSSL_STORE_LOADER_CTX; 295 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_fn) 296 (const OSSL_STORE_LOADER *loader, const char *uri, 297 const UI_METHOD *ui_method, void *ui_data); 298 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_open_ex_fn) 299 (const OSSL_STORE_LOADER *loader, 300 const char *uri, OSSL_LIB_CTX *libctx, const char *propq, 301 const UI_METHOD *ui_method, void *ui_data); 302 303 typedef OSSL_STORE_LOADER_CTX *(*OSSL_STORE_attach_fn) 304 (const OSSL_STORE_LOADER *loader, BIO *bio, 305 OSSL_LIB_CTX *libctx, const char *propq, 306 const UI_METHOD *ui_method, void *ui_data); 307 typedef int (*OSSL_STORE_ctrl_fn) 308 (OSSL_STORE_LOADER_CTX *ctx, int cmd, va_list args); 309 typedef int (*OSSL_STORE_expect_fn) 310 (OSSL_STORE_LOADER_CTX *ctx, int expected); 311 typedef int (*OSSL_STORE_find_fn) 312 (OSSL_STORE_LOADER_CTX *ctx, const OSSL_STORE_SEARCH *criteria); 313 typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn) 314 (OSSL_STORE_LOADER_CTX *ctx, const UI_METHOD *ui_method, void *ui_data); 315 typedef int (*OSSL_STORE_eof_fn)(OSSL_STORE_LOADER_CTX *ctx); 316 typedef int (*OSSL_STORE_error_fn)(OSSL_STORE_LOADER_CTX *ctx); 317 typedef int (*OSSL_STORE_close_fn)(OSSL_STORE_LOADER_CTX *ctx); 318 319 # endif 320 # ifndef OPENSSL_NO_DEPRECATED_3_0 321 OSSL_DEPRECATEDIN_3_0 322 OSSL_STORE_LOADER *OSSL_STORE_LOADER_new(ENGINE *e, const char *scheme); 323 OSSL_DEPRECATEDIN_3_0 324 int OSSL_STORE_LOADER_set_open(OSSL_STORE_LOADER *loader, 325 OSSL_STORE_open_fn open_function); 326 OSSL_DEPRECATEDIN_3_0 327 int OSSL_STORE_LOADER_set_open_ex(OSSL_STORE_LOADER *loader, 328 OSSL_STORE_open_ex_fn open_ex_function); 329 OSSL_DEPRECATEDIN_3_0 330 int OSSL_STORE_LOADER_set_attach(OSSL_STORE_LOADER *loader, 331 OSSL_STORE_attach_fn attach_function); 332 OSSL_DEPRECATEDIN_3_0 333 int OSSL_STORE_LOADER_set_ctrl(OSSL_STORE_LOADER *loader, 334 OSSL_STORE_ctrl_fn ctrl_function); 335 OSSL_DEPRECATEDIN_3_0 336 int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader, 337 OSSL_STORE_expect_fn expect_function); 338 OSSL_DEPRECATEDIN_3_0 339 int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader, 340 OSSL_STORE_find_fn find_function); 341 OSSL_DEPRECATEDIN_3_0 342 int OSSL_STORE_LOADER_set_load(OSSL_STORE_LOADER *loader, 343 OSSL_STORE_load_fn load_function); 344 OSSL_DEPRECATEDIN_3_0 345 int OSSL_STORE_LOADER_set_eof(OSSL_STORE_LOADER *loader, 346 OSSL_STORE_eof_fn eof_function); 347 OSSL_DEPRECATEDIN_3_0 348 int OSSL_STORE_LOADER_set_error(OSSL_STORE_LOADER *loader, 349 OSSL_STORE_error_fn error_function); 350 OSSL_DEPRECATEDIN_3_0 351 int OSSL_STORE_LOADER_set_close(OSSL_STORE_LOADER *loader, 352 OSSL_STORE_close_fn close_function); 353 OSSL_DEPRECATEDIN_3_0 354 const ENGINE *OSSL_STORE_LOADER_get0_engine(const OSSL_STORE_LOADER *loader); 355 OSSL_DEPRECATEDIN_3_0 356 const char *OSSL_STORE_LOADER_get0_scheme(const OSSL_STORE_LOADER *loader); 357 OSSL_DEPRECATEDIN_3_0 358 int OSSL_STORE_register_loader(OSSL_STORE_LOADER *loader); 359 OSSL_DEPRECATEDIN_3_0 360 OSSL_STORE_LOADER *OSSL_STORE_unregister_loader(const char *scheme); 361 # endif 362 363 /*- 364 * Functions to list STORE loaders 365 * ------------------------------- 366 */ 367 # ifndef OPENSSL_NO_DEPRECATED_3_0 368 OSSL_DEPRECATEDIN_3_0 369 int OSSL_STORE_do_all_loaders(void (*do_function)(const OSSL_STORE_LOADER *loader, 370 void *do_arg), 371 void *do_arg); 372 # endif 373 374 # ifdef __cplusplus 375 } 376 # endif 377 #endif 378