1=pod 2 3=head1 NAME 4 5provider - OpenSSL operation implementation providers 6 7=head1 SYNOPSIS 8 9=for openssl generic 10 11#include <openssl/provider.h> 12 13=head1 DESCRIPTION 14 15=head2 General 16 17This page contains information useful to provider authors. 18 19A I<provider>, in OpenSSL terms, is a unit of code that provides one 20or more implementations for various operations for diverse algorithms 21that one might want to perform. 22 23An I<operation> is something one wants to do, such as encryption and 24decryption, key derivation, MAC calculation, signing and verification, 25etc. 26 27An I<algorithm> is a named method to perform an operation. 28Very often, the algorithms revolve around cryptographic operations, 29but may also revolve around other types of operation, such as managing 30certain types of objects. 31 32See L<crypto(7)> for further details. 33 34=head2 Provider 35 36A I<provider> offers an initialization function, as a set of base 37functions in the form of an L<OSSL_DISPATCH(3)> array, and by extension, 38a set of L<OSSL_ALGORITHM(3)>s (see L<openssl-core.h(7)>). 39It may be a dynamically loadable module, or may be built-in, in 40OpenSSL libraries or in the application. 41If it's a dynamically loadable module, the initialization function 42must be named C<OSSL_provider_init> and must be exported. 43If it's built-in, the initialization function may have any name. 44 45The initialization function must have the following signature: 46 47 int NAME(const OSSL_CORE_HANDLE *handle, 48 const OSSL_DISPATCH *in, const OSSL_DISPATCH **out, 49 void **provctx); 50 51I<handle> is the OpenSSL library object for the provider, and works 52as a handle for everything the OpenSSL libraries need to know about 53the provider. 54For the provider itself, it is passed to some of the functions given in the 55dispatch array I<in>. 56 57I<in> is a dispatch array of base functions offered by the OpenSSL 58libraries, and the available functions are further described in 59L<provider-base(7)>. 60 61I<*out> must be assigned a dispatch array of base functions that the 62provider offers to the OpenSSL libraries. 63The functions that may be offered are further described in 64L<provider-base(7)>, and they are the central means of communication 65between the OpenSSL libraries and the provider. 66 67I<*provctx> should be assigned a provider specific context to allow 68the provider multiple simultaneous uses. 69This pointer will be passed to various operation functions offered by 70the provider. 71 72Note that the provider will not be made available for applications to use until 73the initialization function has completed and returned successfully. 74 75One of the functions the provider offers to the OpenSSL libraries is 76the central mechanism for the OpenSSL libraries to get access to 77operation implementations for diverse algorithms. 78Its referred to with the number B<OSSL_FUNC_PROVIDER_QUERY_OPERATION> 79and has the following signature: 80 81 const OSSL_ALGORITHM *provider_query_operation(void *provctx, 82 int operation_id, 83 const int *no_store); 84 85I<provctx> is the provider specific context that was passed back by 86the initialization function. 87 88I<operation_id> is an operation identity (see L</Operations> below). 89 90I<no_store> is a flag back to the OpenSSL libraries which, when 91nonzero, signifies that the OpenSSL libraries will not store a 92reference to the returned data in their internal store of 93implementations. 94 95The returned L<OSSL_ALGORITHM(3)> is the foundation of any OpenSSL 96library API that uses providers for their implementation, most 97commonly in the I<fetching> type of functions 98(see L<crypto(7)/ALGORITHM FETCHING>). 99 100=head2 Operations 101 102Operations are referred to with numbers, via macros with names 103starting with C<OSSL_OP_>. 104 105With each operation comes a set of defined function types that a 106provider may or may not offer, depending on its needs. 107 108Currently available operations are: 109 110=over 4 111 112=item Digests 113 114In the OpenSSL libraries, the corresponding method object is 115B<EVP_MD>. 116The number for this operation is B<OSSL_OP_DIGEST>. 117The functions the provider can offer are described in 118L<provider-digest(7)>. 119 120=item Symmetric ciphers 121 122In the OpenSSL libraries, the corresponding method object is 123B<EVP_CIPHER>. 124The number for this operation is B<OSSL_OP_CIPHER>. 125The functions the provider can offer are described in 126L<provider-cipher(7)>. 127 128=item Message Authentication Code (MAC) 129 130In the OpenSSL libraries, the corresponding method object is 131B<EVP_MAC>. 132The number for this operation is B<OSSL_OP_MAC>. 133The functions the provider can offer are described in 134L<provider-mac(7)>. 135 136=item Key Derivation Function (KDF) 137 138In the OpenSSL libraries, the corresponding method object is 139B<EVP_KDF>. 140The number for this operation is B<OSSL_OP_KDF>. 141The functions the provider can offer are described in 142L<provider-kdf(7)>. 143 144=item Key Exchange 145 146In the OpenSSL libraries, the corresponding method object is 147B<EVP_KEYEXCH>. 148The number for this operation is B<OSSL_OP_KEYEXCH>. 149The functions the provider can offer are described in 150L<provider-keyexch(7)>. 151 152=item Asymmetric Ciphers 153 154In the OpenSSL libraries, the corresponding method object is 155B<EVP_ASYM_CIPHER>. 156The number for this operation is B<OSSL_OP_ASYM_CIPHER>. 157The functions the provider can offer are described in 158L<provider-asym_cipher(7)>. 159 160=item Asymmetric Key Encapsulation 161 162In the OpenSSL libraries, the corresponding method object is B<EVP_KEM>. 163The number for this operation is B<OSSL_OP_KEM>. 164The functions the provider can offer are described in L<provider-kem(7)>. 165 166=item Encoding 167 168In the OpenSSL libraries, the corresponding method object is 169B<OSSL_ENCODER>. 170The number for this operation is B<OSSL_OP_ENCODER>. 171The functions the provider can offer are described in 172L<provider-encoder(7)>. 173 174=item Decoding 175 176In the OpenSSL libraries, the corresponding method object is 177B<OSSL_DECODER>. 178The number for this operation is B<OSSL_OP_DECODER>. 179The functions the provider can offer are described in 180L<provider-decoder(7)>. 181 182=item Random Number Generation 183 184The number for this operation is B<OSSL_OP_RAND>. 185The functions the provider can offer for random number generation are described 186in L<provider-rand(7)>. 187 188=item Key Management 189 190The number for this operation is B<OSSL_OP_KEYMGMT>. 191The functions the provider can offer for key management are described in 192L<provider-keymgmt(7)>. 193 194=item Signing and Signature Verification 195 196The number for this operation is B<OSSL_OP_SIGNATURE>. 197The functions the provider can offer for digital signatures are described in 198L<provider-signature(7)>. 199 200=item Store Management 201 202The number for this operation is B<OSSL_OP_STORE>. 203The functions the provider can offer for store management are described in 204L<provider-storemgmt(7)>. 205 206=back 207 208=head3 Algorithm naming 209 210Algorithm names are case insensitive. Any particular algorithm can have multiple 211aliases associated with it. The canonical OpenSSL naming scheme follows this 212format: 213 214ALGNAME[VERSION?][-SUBNAME[VERSION?]?][-SIZE?][-MODE?] 215 216VERSION is only present if there are multiple versions of an algorithm (e.g. 217MD2, MD4, MD5). It may be omitted if there is only one version. 218 219SUBNAME may be present where multiple algorithms are combined together, 220e.g. MD5-SHA1. 221 222SIZE is only present if multiple versions of an algorithm exist with different 223sizes (e.g. AES-128-CBC, AES-256-CBC) 224 225MODE is only present where applicable. 226 227Other aliases may exist for example where standards bodies or common practice 228use alternative names or names that OpenSSL has used historically. 229 230=head1 OPENSSL PROVIDERS 231 232OpenSSL provides a number of its own providers. These are the default, base, 233fips, legacy and null providers. See L<crypto(7)> for an overview of these 234providers. 235 236=head1 SEE ALSO 237 238L<EVP_DigestInit_ex(3)>, L<EVP_EncryptInit_ex(3)>, 239L<OSSL_LIB_CTX(3)>, 240L<EVP_set_default_properties(3)>, 241L<EVP_MD_fetch(3)>, 242L<EVP_CIPHER_fetch(3)>, 243L<EVP_KEYMGMT_fetch(3)>, 244L<openssl-core.h(7)>, 245L<provider-base(7)>, 246L<provider-digest(7)>, 247L<provider-cipher(7)>, 248L<provider-keyexch(7)> 249 250=head1 HISTORY 251 252The concept of providers and everything surrounding them was 253introduced in OpenSSL 3.0. 254 255=head1 COPYRIGHT 256 257Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved. 258 259Licensed under the Apache License 2.0 (the "License"). You may not use 260this file except in compliance with the License. You can obtain a copy 261in the file LICENSE in the source distribution or at 262L<https://www.openssl.org/source/license.html>. 263 264=cut 265