doc/man7/provider.pod

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