provider-cipher

title: provider-cipher(7ossl)

summary: The cipher library <\-> provider functions

text:
# provider-cipher(7ossl)

## NAME
provider-cipher - The cipher library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Context management */
 void *OSSL_FUNC_cipher_newctx(void *provctx);
 void OSSL_FUNC_cipher_freectx(void *cctx);
 void *OSSL_FUNC_cipher_dupctx(void *cctx);
 /* Encryption/decryption */
 int OSSL_FUNC_cipher_encrypt_init(void *cctx, const unsigned char *key,
                                   size_t keylen, const unsigned char *iv,
                                   size_t ivlen, const OSSL_PARAM params[]);
 int OSSL_FUNC_cipher_decrypt_init(void *cctx, const unsigned char *key,
                                   size_t keylen, const unsigned char *iv,
                                   size_t ivlen, const OSSL_PARAM params[]);
 int OSSL_FUNC_cipher_update(void *cctx, unsigned char *out, size_t *outl,
                             size_t outsize, const unsigned char *in, size_t inl);
 int OSSL_FUNC_cipher_final(void *cctx, unsigned char *out, size_t *outl,
                            size_t outsize);
 int OSSL_FUNC_cipher_cipher(void *cctx, unsigned char *out, size_t *outl,
                             size_t outsize, const unsigned char *in, size_t inl);
 /* Cipher parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_cipher_gettable_params(void *provctx);
 /* Cipher operation parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_cipher_gettable_ctx_params(void *cctx,
                                                        void *provctx);
 const OSSL_PARAM *OSSL_FUNC_cipher_settable_ctx_params(void *cctx,
                                                        void *provctx);
 /* Cipher parameters */
 int OSSL_FUNC_cipher_get_params(OSSL_PARAM params[]);
 /* Cipher operation parameters */
 int OSSL_FUNC_cipher_get_ctx_params(void *cctx, OSSL_PARAM params[]);
 int OSSL_FUNC_cipher_set_ctx_params(void *cctx, const OSSL_PARAM params[]);
```

## DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.

The CIPHER operation enables providers to implement cipher algorithms and make them available to applications via the API functions EVP_EncryptInit_ex(3), EVP_EncryptUpdate(3) and EVP_EncryptFinal(3) (as well as the decrypt equivalents and other related functions).

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_cipher_newctx() has these:

```
 typedef void *(OSSL_FUNC_cipher_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_cipher_newctx_fn
     OSSL_FUNC_cipher_newctx(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_cipher_newctx               OSSL_FUNC_CIPHER_NEWCTX
 OSSL_FUNC_cipher_freectx              OSSL_FUNC_CIPHER_FREECTX
 OSSL_FUNC_cipher_dupctx               OSSL_FUNC_CIPHER_DUPCTX
 OSSL_FUNC_cipher_encrypt_init         OSSL_FUNC_CIPHER_ENCRYPT_INIT
 OSSL_FUNC_cipher_decrypt_init         OSSL_FUNC_CIPHER_DECRYPT_INIT
 OSSL_FUNC_cipher_update               OSSL_FUNC_CIPHER_UPDATE
 OSSL_FUNC_cipher_final                OSSL_FUNC_CIPHER_FINAL
 OSSL_FUNC_cipher_cipher               OSSL_FUNC_CIPHER_CIPHER
 OSSL_FUNC_cipher_get_params           OSSL_FUNC_CIPHER_GET_PARAMS
 OSSL_FUNC_cipher_get_ctx_params       OSSL_FUNC_CIPHER_GET_CTX_PARAMS
 OSSL_FUNC_cipher_set_ctx_params       OSSL_FUNC_CIPHER_SET_CTX_PARAMS
 OSSL_FUNC_cipher_gettable_params      OSSL_FUNC_CIPHER_GETTABLE_PARAMS
 OSSL_FUNC_cipher_gettable_ctx_params  OSSL_FUNC_CIPHER_GETTABLE_CTX_PARAMS
 OSSL_FUNC_cipher_settable_ctx_params  OSSL_FUNC_CIPHER_SETTABLE_CTX_PARAMS
```

A cipher algorithm implementation may not implement all of these functions. In order to be a consistent set of functions there must at least be a complete set of "encrypt" functions, or a complete set of "decrypt" functions, or a single "cipher" function. In all cases both the OSSL_FUNC_cipher_newctx and OSSL_FUNC_cipher_freectx functions must be present. All other functions are optional.

### Context Management Functions
OSSL_FUNC_cipher_newctx() should create and return a pointer to a provider side structure for holding context information during a cipher operation. A pointer to this context will be passed back in a number of the other cipher operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)).

OSSL_FUNC_cipher_freectx() is passed a pointer to the provider side cipher context in the cctx parameter. This function should free any resources associated with that context.

OSSL_FUNC_cipher_dupctx() should duplicate the provider side cipher context in the cctx parameter and return the duplicate copy.

### Encryption/Decryption Functions
OSSL_FUNC_cipher_encrypt_init() initialises a cipher operation for encryption given a newly created provider side cipher context in the cctx parameter. The key to be used is given in key which is keylen bytes long. The IV to be used is given in iv which is ivlen bytes long. The params, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_cipher_set_ctx_params().

OSSL_FUNC_cipher_decrypt_init() is the same as OSSL_FUNC_cipher_encrypt_init() except that it initialises the context for a decryption operation.

OSSL_FUNC_cipher_update() is called to supply data to be encrypted/decrypted as part of a previously initialised cipher operation. The cctx parameter contains a pointer to a previously initialised provider side context. OSSL_FUNC_cipher_update() should encrypt/decrypt inl bytes of data at the location pointed to by in. The encrypted data should be stored in out and the amount of data written to *outl which should not exceed outsize bytes. OSSL_FUNC_cipher_update() may be called multiple times for a single cipher operation. It is the responsibility of the cipher implementation to handle input lengths that are not multiples of the block length. In such cases a cipher implementation will typically cache partial blocks of input data until a complete block is obtained. The pointers out and in may point to the same location, in which case the encryption must be done in-place. If out and in point to different locations, the requirements of EVP_EncryptUpdate(3) and EVP_DecryptUpdate(3) guarantee that the two buffers are disjoint. Similarly, the requirements of EVP_EncryptUpdate(3) and EVP_DecryptUpdate(3) ensure that the buffer pointed to by out contains sufficient room for the operation being performed.

OSSL_FUNC_cipher_final() completes an encryption or decryption started through previous OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(), and OSSL_FUNC_cipher_update() calls. The cctx parameter contains a pointer to the provider side context. Any final encryption/decryption output should be written to out and the amount of data written to *outl which should not exceed outsize bytes. The same expectations apply to outsize as documented for EVP_EncryptFinal(3) and EVP_DecryptFinal(3).

OSSL_FUNC_cipher_cipher() performs encryption/decryption using the provider side cipher context in the cctx parameter that should have been previously initialised via a call to OSSL_FUNC_cipher_encrypt_init() or OSSL_FUNC_cipher_decrypt_init(). This should call the raw underlying cipher function without any padding. This will be invoked in the provider as a result of the application calling EVP_Cipher(3). The application is responsible for ensuring that the input is a multiple of the block length. The data to be encrypted/decrypted will be in in, and it will be inl bytes in length. The output from the encryption/decryption should be stored in out and the amount of data stored should be put in *outl which should be no more than outsize bytes.

### Cipher Parameters
See OSSL_PARAM(3) for further details on the parameters structure used by these functions.

OSSL_FUNC_cipher_get_params() gets details of the algorithm implementation and stores them in params.

OSSL_FUNC_cipher_set_ctx_params() sets cipher operation parameters for the provider side cipher context cctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

OSSL_FUNC_cipher_get_ctx_params() gets cipher operation details details from the given provider side cipher context cctx and stores them in params. Passing NULL for params should return true.

OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params(), and OSSL_FUNC_cipher_settable_ctx_params() all return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_cipher_get_params(), OSSL_FUNC_cipher_get_ctx_params(), and OSSL_FUNC_cipher_set_ctx_params() can handle, respectively. OSSL_FUNC_cipher_gettable_ctx_params() and OSSL_FUNC_cipher_settable_ctx_params() will return the parameters associated with the provider side context cctx in its current state if it is not NULL. Otherwise, they return the parameters associated with the provider side algorithm provctx.

Parameters currently recognised by built-in ciphers are listed in "PARAMETERS" in EVP_EncryptInit(3). Not all parameters are relevant to, or are understood by all ciphers.

## RETURN VALUES
OSSL_FUNC_cipher_newctx() and OSSL_FUNC_cipher_dupctx() should return the newly created provider side cipher context, or NULL on failure.

OSSL_FUNC_cipher_encrypt_init(), OSSL_FUNC_cipher_decrypt_init(), OSSL_FUNC_cipher_update(), OSSL_FUNC_cipher_final(), OSSL_FUNC_cipher_cipher(), OSSL_FUNC_cipher_get_params(), OSSL_FUNC_cipher_get_ctx_params() and OSSL_FUNC_cipher_set_ctx_params() should return 1 for success or 0 on error.

OSSL_FUNC_cipher_gettable_params(), OSSL_FUNC_cipher_gettable_ctx_params() and OSSL_FUNC_cipher_settable_ctx_params() should return a constant OSSL_PARAM(3) array, or NULL if none is offered.

## SEE ALSO
provider(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-legacy(7), EVP_CIPHER-AES(7), EVP_CIPHER-ARIA(7), EVP_CIPHER-BLOWFISH(7), EVP_CIPHER-CAMELLIA(7), EVP_CIPHER-CAST(7), EVP_CIPHER-CHACHA(7), EVP_CIPHER-DES(7), EVP_CIPHER-IDEA(7), EVP_CIPHER-RC2(7), EVP_CIPHER-RC4(7), EVP_CIPHER-RC5(7), EVP_CIPHER-SEED(7), EVP_CIPHER-SM4(7), EVP_CIPHER-NULL(7), life_cycle-cipher(7), EVP_EncryptInit(3)

## HISTORY
The provider CIPHER interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-decoder

package: openssl

title: provider-decoder(7ossl)

summary: The OSSL_DECODER library <\-> provider functions

text:
# provider-decoder(7ossl)

## NAME
provider-decoder - The OSSL_DECODER library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Decoder parameter accessor and descriptor */
 const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
 int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
 /* Functions to construct / destruct / manipulate the decoder context */
 void *OSSL_FUNC_decoder_newctx(void *provctx);
 void OSSL_FUNC_decoder_freectx(void *ctx);
 const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
 int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 /* Functions to check selection support */
 int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
 /* Functions to decode object data */
 int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
                              int selection,
                              OSSL_CALLBACK *data_cb, void *data_cbarg,
                              OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 /* Functions to export a decoded object */
 int OSSL_FUNC_decoder_export_object(void *ctx,
                                       const void *objref, size_t objref_sz,
                                       OSSL_CALLBACK *export_cb,
                                       void *export_cbarg);
```

## DESCRIPTION
The term "decode" is used throughout this manual. This includes but is not limited to deserialization as individual decoders can also do decoding into intermediate data formats.

The DECODER operation is a generic method to create a provider-native object reference or intermediate decoded data from an encoded form read from the given OSSL_CORE_BIO. If the caller wants to decode data from memory, it should provide a BIO_s_mem(3) BIO. The decoded data or object reference is passed along with eventual metadata to the metadata_cb as OSSL_PARAM(3) parameters.

The decoder doesn't need to know more about the OSSL_CORE_BIO pointer than being able to pass it to the appropriate BIO upcalls (see "Core functions" in provider-base(7)).

The DECODER implementation may be part of a chain, where data is passed from one to the next. For example, there may be an implementation to decode an object from PEM to DER, and another one that decodes DER to a provider-native object.

The last decoding step in the decoding chain is usually supposed to create a provider-native object referenced by an object reference. To import that object into a different provider the OSSL_FUNC_decoder_export_object() can be called as the final step of the decoding process.

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_decoder_decode() has these:

```
 typedef int
     (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
                                   int selection,
                                   OSSL_CALLBACK *data_cb, void *data_cbarg,
                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 static ossl_inline OSSL_FUNC_decoder_decode_fn*
     OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
 OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS
 OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
 OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
 OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
 OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
 OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION
 OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE
 OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT
```

### Names and properties
The name of an implementation should match the target type of object it decodes. For example, an implementation that decodes an RSA key should be named "RSA". Likewise, an implementation that decodes DER data from PEM input should be named "DER".

Properties can be used to further specify details about an implementation:

input

This property is used to specify what format of input the implementation can decode. This property is mandatory.

OpenSSL providers recognize the following input types:

pem

An implementation with that input type decodes PEM formatted data.

der

An implementation with that input type decodes DER formatted data.

msblob

An implementation with that input type decodes MSBLOB formatted data.

pvk

An implementation with that input type decodes PVK formatted data.

structure

This property is used to specify the structure that the decoded data is expected to have. This property is optional.

Structures currently recognised by built-in decoders:

"type-specific"

Type specific structure.

"pkcs8"

Structure according to the PKCS#8 specification.

"SubjectPublicKeyInfo"

Encoding of public keys according to the Subject Public Key Info of RFC 5280.

The possible values of both these properties is open ended. A provider may very well specify input types and structures that libcrypto doesn't know anything about.

### Subset selections
Sometimes, an object has more than one subset of data that is interesting to treat separately or together. It's possible to specify what subsets are to be decoded, with a set of bits selection that are passed in an int.

This set of bits depend entirely on what kind of provider-side object is to be decoded. For example, those bits are assumed to be the same as those used with provider-keymgmt(7) (see "Key Objects" in provider-keymgmt(7)) when the object is an asymmetric keypair - e.g., OSSL_KEYMGMT_SELECT_PRIVATE_KEY if the object to be decoded is supposed to contain private key components.

OSSL_FUNC_decoder_does_selection() should tell if a particular implementation supports any of the combinations given by selection.

### Context functions
OSSL_FUNC_decoder_newctx() returns a context to be used with the rest of the functions.

OSSL_FUNC_decoder_freectx() frees the given ctx as created by OSSL_FUNC_decoder_newctx().

OSSL_FUNC_decoder_set_ctx_params() sets context data according to parameters from params that it recognises. Unrecognised parameters should be ignored. Passing NULL for params should return true.

OSSL_FUNC_decoder_settable_ctx_params() returns a constant OSSL_PARAM(3) array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() can handle.

See OSSL_PARAM(3) for further details on the parameters structure used by OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params().

### Export function
When a provider-native object is created by a decoder it would be unsuitable for direct use with a foreign provider. The export function allows for exporting the object into that foreign provider if the foreign provider supports the type of the object and provides an import function.

OSSL_FUNC_decoder_export_object() should export the object of size objref_sz referenced by objref as an OSSL_PARAM(3) array and pass that into the export_cb as well as the given export_cbarg.

### Decoding functions
OSSL_FUNC_decoder_decode() should decode the data as read from the OSSL_CORE_BIO in to produce decoded data or an object to be passed as reference in an OSSL_PARAM(3) array along with possible other metadata that was decoded from the input. This OSSL_PARAM(3) array is then passed to the data_cb callback. The selection bits, if relevant, should determine what the input data should contain. The decoding functions also take an OSSL_PASSPHRASE_CALLBACK(3) function pointer along with a pointer to application data cbarg, which should be used when a pass phrase prompt is needed.

It's important to understand that the return value from this function is interpreted as follows:

True (1)

This means "carry on the decoding process", and is meaningful even though this function couldn't decode the input into anything, because there may be another decoder implementation that can decode it into something. The data_cb callback should never be called when this function can't decode the input into anything.

False (0)

This means "stop the decoding process", and is meaningful when the input could be decoded into some sort of object that this function understands, but further treatment of that object results into errors that won't be possible for some other decoder implementation to get a different result.

The conditions to stop the decoding process are at the discretion of the implementation.

### Decoder operation parameters
There are currently no operation parameters currently recognised by the built-in decoders.

Parameters currently recognised by the built-in pass phrase callback:

"info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>

A string of information that will become part of the pass phrase prompt. This could be used to give the user information on what kind of object it's being prompted for.

## RETURN VALUES
OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on failure.

OSSL_FUNC_decoder_set_ctx_params() returns 1, unless a recognised parameter was invalid or caused an error, for which 0 is returned.

OSSL_FUNC_decoder_settable_ctx_params() returns a pointer to an array of constant OSSL_PARAM(3) elements.

OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation supports any of the selection bits, otherwise 0.

OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding process should continue, or 0 to signal that it should stop.

## SEE ALSO
provider(7)

## HISTORY
The DECODER interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-digest

title: provider-digest(7ossl)

summary: The digest library <\-> provider functions

text:
# provider-digest(7ossl)

## NAME
provider-digest - The digest library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>
 /*
  * Digests support the following function signatures in OSSL_DISPATCH arrays.
  * (The function signatures are not actual functions).
  */
 /* Context management */
 void *OSSL_FUNC_digest_newctx(void *provctx);
 void OSSL_FUNC_digest_freectx(void *dctx);
 void *OSSL_FUNC_digest_dupctx(void *dctx);
 /* Digest generation */
 int OSSL_FUNC_digest_init(void *dctx, const OSSL_PARAM params[]);
 int OSSL_FUNC_digest_update(void *dctx, const unsigned char *in, size_t inl);
 int OSSL_FUNC_digest_final(void *dctx, unsigned char *out, size_t *outl,
                            size_t outsz);
 int OSSL_FUNC_digest_digest(void *provctx, const unsigned char *in, size_t inl,
                             unsigned char *out, size_t *outl, size_t outsz);
 /* Digest parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_digest_gettable_params(void *provctx);
 /* Digest operation parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_digest_gettable_ctx_params(void *dctx,
                                                        void *provctx);
 const OSSL_PARAM *OSSL_FUNC_digest_settable_ctx_params(void *dctx,
                                                        void *provctx);
 /* Digest parameters */
 int OSSL_FUNC_digest_get_params(OSSL_PARAM params[]);
 /* Digest operation parameters */
 int OSSL_FUNC_digest_set_ctx_params(void *dctx, const OSSL_PARAM params[]);
 int OSSL_FUNC_digest_get_ctx_params(void *dctx, OSSL_PARAM params[]);
```

## DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.

The DIGEST operation enables providers to implement digest algorithms and make them available to applications via the API functions EVP_DigestInit_ex(3), EVP_DigestUpdate(3) and EVP_DigestFinal(3) (and other related functions).

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_digest_newctx() has these:

```
 typedef void *(OSSL_FUNC_digest_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_digest_newctx_fn
     OSSL_FUNC_digest_newctx(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_digest_newctx               OSSL_FUNC_DIGEST_NEWCTX
 OSSL_FUNC_digest_freectx              OSSL_FUNC_DIGEST_FREECTX
 OSSL_FUNC_digest_dupctx               OSSL_FUNC_DIGEST_DUPCTX
 OSSL_FUNC_digest_init                 OSSL_FUNC_DIGEST_INIT
 OSSL_FUNC_digest_update               OSSL_FUNC_DIGEST_UPDATE
 OSSL_FUNC_digest_final                OSSL_FUNC_DIGEST_FINAL
 OSSL_FUNC_digest_digest               OSSL_FUNC_DIGEST_DIGEST
 OSSL_FUNC_digest_get_params           OSSL_FUNC_DIGEST_GET_PARAMS
 OSSL_FUNC_digest_get_ctx_params       OSSL_FUNC_DIGEST_GET_CTX_PARAMS
 OSSL_FUNC_digest_set_ctx_params       OSSL_FUNC_DIGEST_SET_CTX_PARAMS
 OSSL_FUNC_digest_gettable_params      OSSL_FUNC_DIGEST_GETTABLE_PARAMS
 OSSL_FUNC_digest_gettable_ctx_params  OSSL_FUNC_DIGEST_GETTABLE_CTX_PARAMS
 OSSL_FUNC_digest_settable_ctx_params  OSSL_FUNC_DIGEST_SETTABLE_CTX_PARAMS
```

A digest algorithm implementation may not implement all of these functions. In order to be usable all or none of OSSL_FUNC_digest_newctx, OSSL_FUNC_digest_freectx, OSSL_FUNC_digest_init, OSSL_FUNC_digest_update and OSSL_FUNC_digest_final should be implemented. All other functions are optional.

### Context Management Functions
OSSL_FUNC_digest_newctx() should create and return a pointer to a provider side structure for holding context information during a digest operation. A pointer to this context will be passed back in a number of the other digest operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)).

OSSL_FUNC_digest_freectx() is passed a pointer to the provider side digest context in the dctx parameter. This function should free any resources associated with that context.

OSSL_FUNC_digest_dupctx() should duplicate the provider side digest context in the dctx parameter and return the duplicate copy.

### Digest Generation Functions
OSSL_FUNC_digest_init() initialises a digest operation given a newly created provider side digest context in the dctx parameter. The params, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_digest_set_ctx_params().

OSSL_FUNC_digest_update() is called to supply data to be digested as part of a previously initialised digest operation. The dctx parameter contains a pointer to a previously initialised provider side context. OSSL_FUNC_digest_update() should digest inl bytes of data at the location pointed to by in. OSSL_FUNC_digest_update() may be called multiple times for a single digest operation.

OSSL_FUNC_digest_final() generates a digest started through previous OSSL_FUNC_digest_init() and OSSL_FUNC_digest_update() calls. The dctx parameter contains a pointer to the provider side context. The digest should be written to *out and the length of the digest to *outl. The digest should not exceed outsz bytes.

OSSL_FUNC_digest_digest() is a "oneshot" digest function. No provider side digest context is used. Instead the provider context that was created during provider initialisation is passed in the provctx parameter (see provider(7)). inl bytes at in should be digested and the result should be stored at out. The length of the digest should be stored in *outl which should not exceed outsz bytes.

### Digest Parameters
See OSSL_PARAM(3) for further details on the parameters structure used by these functions.

OSSL_FUNC_digest_get_params() gets details of the algorithm implementation and stores them in params.

OSSL_FUNC_digest_set_ctx_params() sets digest operation parameters for the provider side digest context dctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

OSSL_FUNC_digest_get_ctx_params() gets digest operation details details from the given provider side digest context dctx and stores them in params. Passing NULL for params should return true.

OSSL_FUNC_digest_gettable_params() returns a constant OSSL_PARAM(3) array containing descriptors of the parameters that OSSL_FUNC_digest_get_params() can handle.

OSSL_FUNC_digest_gettable_ctx_params() and OSSL_FUNC_digest_settable_ctx_params() both return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_digest_get_ctx_params() and OSSL_FUNC_digest_set_ctx_params() can handle, respectively. The array is based on the current state of the provider side context if dctx is not NULL and on the provider side algorithm provctx otherwise.

Parameters currently recognised by built-in digests with this function are as follows. Not all parameters are relevant to, or are understood by all digests:

"blocksize" (OSSL_DIGEST_PARAM_BLOCK_SIZE) <unsigned integer>

The digest block size. The length of the "blocksize" parameter should not exceed that of a size_t.

"size" (OSSL_DIGEST_PARAM_SIZE) <unsigned integer>

The digest output size. The length of the "size" parameter should not exceed that of a size_t.

"flags" (OSSL_DIGEST_PARAM_FLAGS) <unsigned integer>

Diverse flags that describe exceptional behaviour for the digest:

EVP_MD_FLAG_ONESHOT

This digest method can only handle one block of input.

EVP_MD_FLAG_XOF

This digest method is an extensible-output function (XOF).

EVP_MD_FLAG_DIGALGID_NULL

When setting up a DigestAlgorithmIdentifier, this flag will have the parameter set to NULL by default. Use this for PKCS#1. Note: if combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.

EVP_MD_FLAG_DIGALGID_ABSENT

When setting up a DigestAlgorithmIdentifier, this flag will have the parameter be left absent by default. Note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.

EVP_MD_FLAG_DIGALGID_CUSTOM

Custom DigestAlgorithmIdentifier handling via ctrl, with EVP_MD_FLAG_DIGALGID_ABSENT as default. Note: if combined with EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden. Currently unused.

The length of the "flags" parameter should equal that of an unsigned long int.

### Digest Context Parameters
OSSL_FUNC_digest_set_ctx_params() sets digest parameters associated with the given provider side digest context dctx to params. Any parameter settings are additional to any that were previously set. See OSSL_PARAM(3) for further details on the parameters structure.

OSSL_FUNC_digest_get_ctx_params() gets details of currently set parameters values associated with the give provider side digest context dctx and stores them in params. See OSSL_PARAM(3) for further details on the parameters structure.

## RETURN VALUES
OSSL_FUNC_digest_newctx() and OSSL_FUNC_digest_dupctx() should return the newly created provider side digest context, or NULL on failure.

OSSL_FUNC_digest_init(), OSSL_FUNC_digest_update(), OSSL_FUNC_digest_final(), OSSL_FUNC_digest_digest(), OSSL_FUNC_digest_set_params() and OSSL_FUNC_digest_get_params() should return 1 for success or 0 on error.

OSSL_FUNC_digest_size() should return the digest size.

OSSL_FUNC_digest_block_size() should return the block size of the underlying digest algorithm.

## BUGS
The EVP_Q_digest(), EVP_Digest() and EVP_DigestFinal_ex() API calls do not expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which produces larger digests is unusable with those API calls.

## SEE ALSO
provider(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-legacy(7), EVP_MD-common(7), EVP_MD-BLAKE2(7), EVP_MD-MD2(7), EVP_MD-MD4(7), EVP_MD-MD5(7), EVP_MD-MD5-SHA1(7), EVP_MD-MDC2(7), EVP_MD-RIPEMD160(7), EVP_MD-SHA1(7), EVP_MD-SHA2(7), EVP_MD-SHA3(7), EVP_MD-KECCAK(7) EVP_MD-SHAKE(7), EVP_MD-SM3(7), EVP_MD-WHIRLPOOL(7), EVP_MD-NULL(7), life_cycle-digest(7), EVP_DigestInit(3)

## HISTORY
The provider DIGEST interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-encoder

title: provider-encoder(7ossl)

summary: The OSSL_ENCODER library <\-> provider functions

text:
# provider-encoder(7ossl)

## NAME
provider-encoder - The OSSL_ENCODER library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Encoder parameter accessor and descriptor */
 const OSSL_PARAM *OSSL_FUNC_encoder_gettable_params(void *provctx);
 int OSSL_FUNC_encoder_get_params(OSSL_PARAM params[]);
 /* Functions to construct / destruct / manipulate the encoder context */
 void *OSSL_FUNC_encoder_newctx(void *provctx);
 void OSSL_FUNC_encoder_freectx(void *ctx);
 int OSSL_FUNC_encoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_encoder_settable_ctx_params(void *provctx);
 /* Functions to check selection support */
 int OSSL_FUNC_encoder_does_selection(void *provctx, int selection);
 /* Functions to encode object data */
 int OSSL_FUNC_encoder_encode(void *ctx, OSSL_CORE_BIO *out,
                              const void *obj_raw,
                              const OSSL_PARAM obj_abstract[],
                              int selection,
                              OSSL_PASSPHRASE_CALLBACK *cb,
                              void *cbarg);
 /* Functions to import and free a temporary object to be encoded */
 void *OSSL_FUNC_encoder_import_object(void *ctx, int selection,
                                       const OSSL_PARAM params[]);
 void OSSL_FUNC_encoder_free_object(void *obj);
```

## DESCRIPTION
We use the wide term "encode" in this manual. This includes but is not limited to serialization.

The ENCODER operation is a generic method to encode a provider-native object (obj_raw) or an object abstraction (object_abstract, see provider-object(7)) into an encoded form, and write the result to the given OSSL_CORE_BIO. If the caller wants to get the encoded stream to memory, it should provide a BIO_s_mem(3) BIO.

The encoder doesn't need to know more about the OSSL_CORE_BIO pointer than being able to pass it to the appropriate BIO upcalls (see "Core functions" in provider-base(7)).

The ENCODER implementation may be part of a chain, where data is passed from one to the next. For example, there may be an implementation to encode an object to DER (that object is assumed to be provider-native and thereby passed via obj_raw), and another one that encodes DER to PEM (that one would receive the DER encoding via obj_abstract).

The encoding using the OSSL_PARAM(3) array form allows a encoder to be used for data that's been exported from another provider, and thereby allow them to exist independently of each other.

The encoding using a provider side object can only be safely used with provider data coming from the same provider, for example keys with the KEYMGMT provider.

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_encoder_encode() has these:

```
 typedef int
     (OSSL_FUNC_encoder_encode_fn)(void *ctx, OSSL_CORE_BIO *out,
                                   const void *obj_raw,
                                   const OSSL_PARAM obj_abstract[],
                                   int selection,
                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 static ossl_inline OSSL_FUNC_encoder_encode_fn
     OSSL_FUNC_encoder_encode(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_encoder_get_params          OSSL_FUNC_ENCODER_GET_PARAMS
 OSSL_FUNC_encoder_gettable_params     OSSL_FUNC_ENCODER_GETTABLE_PARAMS
 OSSL_FUNC_encoder_newctx              OSSL_FUNC_ENCODER_NEWCTX
 OSSL_FUNC_encoder_freectx             OSSL_FUNC_ENCODER_FREECTX
 OSSL_FUNC_encoder_set_ctx_params      OSSL_FUNC_ENCODER_SET_CTX_PARAMS
 OSSL_FUNC_encoder_settable_ctx_params OSSL_FUNC_ENCODER_SETTABLE_CTX_PARAMS
 OSSL_FUNC_encoder_does_selection      OSSL_FUNC_ENCODER_DOES_SELECTION
 OSSL_FUNC_encoder_encode              OSSL_FUNC_ENCODER_ENCODE
 OSSL_FUNC_encoder_import_object       OSSL_FUNC_ENCODER_IMPORT_OBJECT
 OSSL_FUNC_encoder_free_object         OSSL_FUNC_ENCODER_FREE_OBJECT
```

### Names and properties
The name of an implementation should match the type of object it handles. For example, an implementation that encodes an RSA key should be named "RSA". Likewise, an implementation that further encodes DER should be named "DER".

Properties can be used to further specify details about an implementation:

output

This property is used to specify what type of output the implementation produces. This property is mandatory.

OpenSSL providers recognize the following output types:

text

An implementation with that output type outputs human readable text, making that implementation suitable for "-text" output in diverse openssl(1) commands.

pem

An implementation with that output type outputs PEM formatted data.

der

An implementation with that output type outputs DER formatted data.

msblob

An implementation with that output type outputs MSBLOB formatted data.

pvk

An implementation with that output type outputs PVK formatted data.

structure

This property is used to specify the structure that is used for the encoded object. An example could be "pkcs8", to specify explicitly that an object (presumably an asymmetric key pair, in this case) will be wrapped in a PKCS#8 structure as part of the encoding. This property is optional.

The possible values of both these properties is open ended. A provider may very well specify output types and structures that libcrypto doesn't know anything about.

### Subset selections
Sometimes, an object has more than one subset of data that is interesting to treat separately or together. It's possible to specify what subsets are to be encoded, with a set of bits selection that are passed in an int.

This set of bits depend entirely on what kind of provider-side object is passed. For example, those bits are assumed to be the same as those used with provider-keymgmt(7) (see "Key Objects" in provider-keymgmt(7)) when the object is an asymmetric keypair.

ENCODER implementations are free to regard the selection as a set of hints, but must do so with care. In the end, the output must make sense, and if there's a corresponding decoder, the resulting decoded object must match the original object that was encoded.

OSSL_FUNC_encoder_does_selection() should tell if a particular implementation supports any of the combinations given by selection.

### Context functions
OSSL_FUNC_encoder_newctx() returns a context to be used with the rest of the functions.

OSSL_FUNC_encoder_freectx() frees the given ctx, if it was created by OSSL_FUNC_encoder_newctx().

OSSL_FUNC_encoder_set_ctx_params() sets context data according to parameters from params that it recognises. Unrecognised parameters should be ignored. Passing NULL for params should return true.

OSSL_FUNC_encoder_settable_ctx_params() returns a constant OSSL_PARAM(3) array describing the parameters that OSSL_FUNC_encoder_set_ctx_params() can handle.

See OSSL_PARAM(3) for further details on the parameters structure used by OSSL_FUNC_encoder_set_ctx_params() and OSSL_FUNC_encoder_settable_ctx_params().

### Import functions
A provider-native object may be associated with a foreign provider, and may therefore be unsuitable for direct use with a given ENCODER implementation. Provided that the foreign provider's implementation to handle the object has a function to export that object in OSSL_PARAM(3) array form, the ENCODER implementation should be able to import that array and create a suitable object to be passed to OSSL_FUNC_encoder_encode()'s obj_raw.

OSSL_FUNC_encoder_import_object() should import the subset of params given with selection to create a provider-native object that can be passed as obj_raw to OSSL_FUNC_encoder_encode().

OSSL_FUNC_encoder_free_object() should free the object that was created with OSSL_FUNC_encoder_import_object().

### Encoding functions
OSSL_FUNC_encoder_encode() should take a provider-native object (in obj_raw) or an object abstraction (in obj_abstract), and should output the object in encoded form to the OSSL_CORE_BIO. The selection bits, if relevant, should determine in greater detail what will be output. The encoding functions also take an OSSL_PASSPHRASE_CALLBACK(3) function pointer along with a pointer to application data cbarg, which should be used when a pass phrase prompt is needed.

### Encoder operation parameters
Operation parameters currently recognised by built-in encoders are as follows:

"cipher" (OSSL_ENCODER_PARAM_CIPHER) <UTF8 string>

The name of the encryption cipher to be used when generating encrypted encoding. This is used when encoding private keys, as well as other objects that need protection. If this name is invalid for the encoding implementation, the implementation should refuse to perform the encoding, i.e. OSSL_FUNC_encoder_encode_data() and OSSL_FUNC_encoder_encode_object() should return an error.

"properties" (OSSL_ENCODER_PARAM_PROPERTIES) <UTF8 string>

The properties to be queried when trying to fetch the algorithm given with the "cipher" parameter. This must be given together with the "cipher" parameter to be considered valid. The encoding implementation isn't obligated to use this value. However, it is recommended that implementations that do not handle property strings return an error on receiving this parameter unless its value NULL or the empty string.

"save-parameters" (OSSL_ENCODER_PARAM_SAVE_PARAMETERS) <integer>

If set to 0 disables saving of key domain parameters. Default is 1. It currently has an effect only on DSA keys.

Parameters currently recognised by the built-in pass phrase callback:

"info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>

A string of information that will become part of the pass phrase prompt. This could be used to give the user information on what kind of object it's being prompted for.

## RETURN VALUES
OSSL_FUNC_encoder_newctx() returns a pointer to a context, or NULL on failure.

OSSL_FUNC_encoder_set_ctx_params() returns 1, unless a recognised parameter was invalid or caused an error, for which 0 is returned.

OSSL_FUNC_encoder_settable_ctx_params() returns a pointer to an array of constant OSSL_PARAM(3) elements.

OSSL_FUNC_encoder_does_selection() returns 1 if the encoder implementation supports any of the selection bits, otherwise 0.

OSSL_FUNC_encoder_encode() returns 1 on success, or 0 on failure.

## SEE ALSO
provider(7)

## HISTORY
The ENCODER interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-kdf

title: provider-kdf(7ossl)

summary: The KDF library <\-> provider functions

text:
# provider-kdf(7ossl)

## NAME
provider-kdf - The KDF library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Context management */
 void *OSSL_FUNC_kdf_newctx(void *provctx);
 void OSSL_FUNC_kdf_freectx(void *kctx);
 void *OSSL_FUNC_kdf_dupctx(void *src);
 /* Encryption/decryption */
 int OSSL_FUNC_kdf_reset(void *kctx);
 int OSSL_FUNC_kdf_derive(void *kctx, unsigned char *key, size_t keylen,
                          const OSSL_PARAM params[]);
 /* KDF parameter descriptors */
 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_params(void *provctx);
 const OSSL_PARAM *OSSL_FUNC_kdf_gettable_ctx_params(void *kcxt, void *provctx);
 const OSSL_PARAM *OSSL_FUNC_kdf_settable_ctx_params(void *kcxt, void *provctx);
 /* KDF parameters */
 int OSSL_FUNC_kdf_get_params(OSSL_PARAM params[]);
 int OSSL_FUNC_kdf_get_ctx_params(void *kctx, OSSL_PARAM params[]);
 int OSSL_FUNC_kdf_set_ctx_params(void *kctx, const OSSL_PARAM params[]);
```

## DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.

The KDF operation enables providers to implement KDF algorithms and make them available to applications via the API functions EVP_KDF_CTX_reset(3), and EVP_KDF_derive(3).

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_kdf_newctx() has these:

```
 typedef void *(OSSL_FUNC_kdf_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_kdf_newctx_fn
     OSSL_FUNC_kdf_newctx(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) array entries are identified by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_kdf_newctx               OSSL_FUNC_KDF_NEWCTX
 OSSL_FUNC_kdf_freectx              OSSL_FUNC_KDF_FREECTX
 OSSL_FUNC_kdf_dupctx               OSSL_FUNC_KDF_DUPCTX
 OSSL_FUNC_kdf_reset                OSSL_FUNC_KDF_RESET
 OSSL_FUNC_kdf_derive               OSSL_FUNC_KDF_DERIVE
 OSSL_FUNC_kdf_get_params           OSSL_FUNC_KDF_GET_PARAMS
 OSSL_FUNC_kdf_get_ctx_params       OSSL_FUNC_KDF_GET_CTX_PARAMS
 OSSL_FUNC_kdf_set_ctx_params       OSSL_FUNC_KDF_SET_CTX_PARAMS
 OSSL_FUNC_kdf_gettable_params      OSSL_FUNC_KDF_GETTABLE_PARAMS
 OSSL_FUNC_kdf_gettable_ctx_params  OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS
 OSSL_FUNC_kdf_settable_ctx_params  OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS
```

A KDF algorithm implementation may not implement all of these functions. In order to be a consistent set of functions, at least the following functions must be implemented: OSSL_FUNC_kdf_newctx(), OSSL_FUNC_kdf_freectx(), OSSL_FUNC_kdf_set_ctx_params(), OSSL_FUNC_kdf_derive(). All other functions are optional.

### Context Management Functions
OSSL_FUNC_kdf_newctx() should create and return a pointer to a provider side structure for holding context information during a KDF operation. A pointer to this context will be passed back in a number of the other KDF operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)).

OSSL_FUNC_kdf_freectx() is passed a pointer to the provider side KDF context in the kctx parameter. If it receives NULL as kctx value, it should not do anything other than return. This function should free any resources associated with that context.

OSSL_FUNC_kdf_dupctx() should duplicate the provider side KDF context in the kctx parameter and return the duplicate copy.

### Encryption/Decryption Functions
OSSL_FUNC_kdf_reset() initialises a KDF operation given a provider side KDF context in the kctx parameter.

OSSL_FUNC_kdf_derive() performs the KDF operation after processing the params as per OSSL_FUNC_kdf_set_ctx_params(). The kctx parameter contains a pointer to the provider side context. The resulting key of the desired keylen should be written to key. If the algorithm does not support the requested keylen the function must return error.

### KDF Parameters
See OSSL_PARAM(3) for further details on the parameters structure used by these functions.

OSSL_FUNC_kdf_get_params() gets details of parameter values associated with the provider algorithm and stores them in params.

OSSL_FUNC_kdf_set_ctx_params() sets KDF parameters associated with the given provider side KDF context kctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

OSSL_FUNC_kdf_get_ctx_params() retrieves gettable parameter values associated with the given provider side KDF context kctx and stores them in params. Passing NULL for params should return true.

OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params(), and OSSL_FUNC_kdf_settable_ctx_params() all return constant OSSL_PARAM(3) arrays as descriptors of the parameters that OSSL_FUNC_kdf_get_params(), OSSL_FUNC_kdf_get_ctx_params(), and OSSL_FUNC_kdf_set_ctx_params() can handle, respectively. OSSL_FUNC_kdf_gettable_ctx_params() and OSSL_FUNC_kdf_settable_ctx_params() will return the parameters associated with the provider side context kctx in its current state if it is not NULL. Otherwise, they return the parameters associated with the provider side algorithm provctx.

Parameters currently recognised by built-in KDFs are as follows. Not all parameters are relevant to, or are understood by all KDFs:

"size" (OSSL_KDF_PARAM_SIZE) <unsigned integer>

Gets the output size from the associated KDF ctx. If the algorithm produces a variable amount of output, SIZE_MAX should be returned. If the input parameters required to calculate the fixed output size have not yet been supplied, 0 should be returned indicating an error.

"key" (OSSL_KDF_PARAM_KEY) <octet string>

Sets the key in the associated KDF ctx.

"secret" (OSSL_KDF_PARAM_SECRET) <octet string>

Sets the secret in the associated KDF ctx.

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

Sets the password in the associated KDF ctx.

"cipher" (OSSL_KDF_PARAM_CIPHER) <UTF8 string>

"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>

"mac" (OSSL_KDF_PARAM_MAC) <UTF8 string>

Sets the name of the underlying cipher, digest or MAC to be used. It must name a suitable algorithm for the KDF that's being used.

"maclen" (OSSL_KDF_PARAM_MAC_SIZE) <octet string>

Sets the length of the MAC in the associated KDF ctx.

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

Sets the properties to be queried when trying to fetch the underlying algorithm. This must be given together with the algorithm naming parameter to be considered valid.

"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>

Sets the number of iterations in the associated KDF ctx.

"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string>

Sets the mode in the associated KDF ctx.

"pkcs5" (OSSL_KDF_PARAM_PKCS5) <integer>

Enables or disables the SP800-132 compliance checks. A mode of 0 enables the compliance checks. The checks performed are:

- the iteration count is at least 1000.

- the salt length is at least 128 bits.

- the derived key length is at least 112 bits.

"ukm" (OSSL_KDF_PARAM_UKM) <octet string>

Sets an optional random string that is provided by the sender called "partyAInfo". In CMS this is the user keying material.

"cekalg" (OSSL_KDF_PARAM_CEK_ALG) <UTF8 string>

Sets the CEK wrapping algorithm name in the associated KDF ctx.

"n" (OSSL_KDF_PARAM_SCRYPT_N) <unsigned integer>

Sets the scrypt work factor parameter N in the associated KDF ctx.

"r" (OSSL_KDF_PARAM_SCRYPT_R) <unsigned integer>

Sets the scrypt work factor parameter r in the associated KDF ctx.

"p" (OSSL_KDF_PARAM_SCRYPT_P) <unsigned integer>

Sets the scrypt work factor parameter p in the associated KDF ctx.

"maxmem_bytes" (OSSL_KDF_PARAM_SCRYPT_MAXMEM) <unsigned integer>

Sets the scrypt work factor parameter maxmem in the associated KDF ctx.

"prefix" (OSSL_KDF_PARAM_PREFIX) <octet string>

Sets the prefix string using by the TLS 1.3 version of HKDF in the associated KDF ctx.

"label" (OSSL_KDF_PARAM_LABEL) <octet string>

Sets the label string using by the TLS 1.3 version of HKDF in the associated KDF ctx.

"data" (OSSL_KDF_PARAM_DATA) <octet string>

Sets the context string using by the TLS 1.3 version of HKDF in the associated KDF ctx.

"info" (OSSL_KDF_PARAM_INFO) <octet string>

Sets the optional shared info in the associated KDF ctx.

"seed" (OSSL_KDF_PARAM_SEED) <octet string>

Sets the IV in the associated KDF ctx.

"xcghash" (OSSL_KDF_PARAM_SSHKDF_XCGHASH) <octet string>

Sets the xcghash in the associated KDF ctx.

"session_id" (OSSL_KDF_PARAM_SSHKDF_SESSION_ID) <octet string>

Sets the session ID in the associated KDF ctx.

"type" (OSSL_KDF_PARAM_SSHKDF_TYPE) <UTF8 string>

Sets the SSH KDF type parameter in the associated KDF ctx. There are six supported types:

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV

The Initial IV from client to server. A single char of value 65 (ASCII char 'A').

EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI

The Initial IV from server to client A single char of value 66 (ASCII char 'B').

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV

The Encryption Key from client to server A single char of value 67 (ASCII char 'C').

EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI

The Encryption Key from server to client A single char of value 68 (ASCII char 'D').

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV

The Integrity Key from client to server A single char of value 69 (ASCII char 'E').

EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI

The Integrity Key from client to server A single char of value 70 (ASCII char 'F').

"constant" (OSSL_KDF_PARAM_CONSTANT) <octet string>

Sets the constant value in the associated KDF ctx.

"id" (OSSL_KDF_PARAM_PKCS12_ID) <integer>

Sets the intended usage of the output bits in the associated KDF ctx. It is defined as per RFC 7292 section B.3.

## RETURN VALUES
OSSL_FUNC_kdf_newctx() and OSSL_FUNC_kdf_dupctx() should return the newly created provider side KDF context, or NULL on failure.

OSSL_FUNC_kdf_derive(), OSSL_FUNC_kdf_get_params(), OSSL_FUNC_kdf_get_ctx_params() and OSSL_FUNC_kdf_set_ctx_params() should return 1 for success or 0 on error.

OSSL_FUNC_kdf_gettable_params(), OSSL_FUNC_kdf_gettable_ctx_params() and OSSL_FUNC_kdf_settable_ctx_params() should return a constant OSSL_PARAM(3) array, or NULL if none is offered.

## NOTES
The KDF life-cycle is described in life_cycle-kdf(7). Providers should ensure that the various transitions listed there are supported. At some point the EVP layer will begin enforcing the listed transitions.

## SEE ALSO
provider(7), life_cycle-kdf(7), EVP_KDF(3).

## HISTORY
The provider KDF interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-kem

title: provider-kem(7ossl)

summary: The kem library <\-> provider functions

text:
# provider-kem(7ossl)

## NAME
provider-kem - The kem library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Context management */
 void *OSSL_FUNC_kem_newctx(void *provctx);
 void OSSL_FUNC_kem_freectx(void *ctx);
 void *OSSL_FUNC_kem_dupctx(void *ctx);
 /* Encapsulation */
 int OSSL_FUNC_kem_encapsulate_init(void *ctx, void *provkey,
                                    const OSSL_PARAM params[]);
 int OSSL_FUNC_kem_auth_encapsulate_init(void *ctx, void *provkey,
                                         void *provauthkey,
                                         const OSSL_PARAM params[]);
 int OSSL_FUNC_kem_encapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               unsigned char *secret, size_t *secretlen);
 /* Decapsulation */
 int OSSL_FUNC_kem_decapsulate_init(void *ctx, void *provkey);
 int OSSL_FUNC_kem_auth_decapsulate_init(void *ctx, void *provkey,
                                         void *provauthkey,
                                         const OSSL_PARAM params[]);
 int OSSL_FUNC_kem_decapsulate(void *ctx, unsigned char *out, size_t *outlen,
                               const unsigned char *in, size_t inlen);
 /* KEM parameters */
 int OSSL_FUNC_kem_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_gettable_ctx_params(void *ctx, void *provctx);
 int OSSL_FUNC_kem_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_kem_settable_ctx_params(void *ctx, void *provctx);
```

## DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.

The asymmetric kem (OSSL_OP_KEM) operation enables providers to implement asymmetric kem algorithms and make them available to applications via the API functions EVP_PKEY_encapsulate(3), EVP_PKEY_decapsulate(3) and other related functions.

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_kem_newctx() has these:

```
 typedef void *(OSSL_FUNC_kem_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_kem_newctx_fn
     OSSL_FUNC_kem_newctx(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_kem_newctx                OSSL_FUNC_KEM_NEWCTX
 OSSL_FUNC_kem_freectx               OSSL_FUNC_KEM_FREECTX
 OSSL_FUNC_kem_dupctx                OSSL_FUNC_KEM_DUPCTX
 OSSL_FUNC_kem_encapsulate_init      OSSL_FUNC_KEM_ENCAPSULATE_INIT
 OSSL_FUNC_kem_auth_encapsulate_init OSSL_FUNC_KEM_AUTH_ENCAPSULATE_INIT
 OSSL_FUNC_kem_encapsulate           OSSL_FUNC_KEM_ENCAPSULATE
 OSSL_FUNC_kem_decapsulate_init      OSSL_FUNC_KEM_DECAPSULATE_INIT
 OSSL_FUNC_kem_auth_decapsulate_init OSSL_FUNC_KEM_AUTH_DECAPSULATE_INIT
 OSSL_FUNC_kem_decapsulate           OSSL_FUNC_KEM_DECAPSULATE
 OSSL_FUNC_kem_get_ctx_params        OSSL_FUNC_KEM_GET_CTX_PARAMS
 OSSL_FUNC_kem_gettable_ctx_params   OSSL_FUNC_KEM_GETTABLE_CTX_PARAMS
 OSSL_FUNC_kem_set_ctx_params        OSSL_FUNC_KEM_SET_CTX_PARAMS
 OSSL_FUNC_kem_settable_ctx_params   OSSL_FUNC_KEM_SETTABLE_CTX_PARAMS
```

An asymmetric kem algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement OSSL_FUNC_kem_newctx and OSSL_FUNC_kem_freectx. It must also implement both of OSSL_FUNC_kem_encapsulate_init and OSSL_FUNC_kem_encapsulate, or both of OSSL_FUNC_kem_decapsulate_init and OSSL_FUNC_kem_decapsulate. OSSL_FUNC_kem_auth_encapsulate_init is optional but if it is present then so must OSSL_FUNC_kem_auth_decapsulate_init. OSSL_FUNC_kem_get_ctx_params is optional but if it is present then so must OSSL_FUNC_kem_gettable_ctx_params. Similarly, OSSL_FUNC_kem_set_ctx_params is optional but if it is present then OSSL_FUNC_kem_settable_ctx_params must also be present.

An asymmetric kem algorithm must also implement some mechanism for generating, loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. See provider-keymgmt(7) for further details.

### Context Management Functions
OSSL_FUNC_kem_newctx() should create and return a pointer to a provider side structure for holding context information during an asymmetric kem operation. A pointer to this context will be passed back in a number of the other asymmetric kem operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)).

OSSL_FUNC_kem_freectx() is passed a pointer to the provider side asymmetric kem context in the ctx parameter. This function should free any resources associated with that context.

OSSL_FUNC_kem_dupctx() should duplicate the provider side asymmetric kem context in the ctx parameter and return the duplicate copy.

### Asymmetric Key Encapsulation Functions
OSSL_FUNC_kem_encapsulate_init() initialises a context for an asymmetric encapsulation given a provider side asymmetric kem context in the ctx parameter, a pointer to a provider key object in the provkey parameter and the name of the algorithm. The params, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_kem_set_ctx_params(). The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.

OSSL_FUNC_kem_auth_encapsulate_init() is similar to OSSL_FUNC_kem_encapsulate_init(), but also passes an additional authentication key provauthkey which cannot be NULL.

OSSL_FUNC_kem_encapsulate() performs the actual encapsulation itself. A previously initialised asymmetric kem context is passed in the ctx parameter. Unless out is NULL, the data to be encapsulated is internally generated, and returned into the buffer pointed to by the secret parameter and the encapsulated data should also be written to the location pointed to by the out parameter. The length of the encapsulated data should be written to *outlen and the length of the generated secret should be written to *secretlen.

If out is NULL then the maximum length of the encapsulated data should be written to *outlen, and the maximum length of the generated secret should be written to *secretlen.

### Decapsulation Functions
OSSL_FUNC_kem_decapsulate_init() initialises a context for an asymmetric decapsulation given a provider side asymmetric kem context in the ctx parameter, a pointer to a provider key object in the provkey parameter, and a name of the algorithm. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.

OSSL_FUNC_kem_auth_decapsulate_init() is similar to OSSL_FUNC_kem_decapsulate_init(), but also passes an additional authentication key provauthkey which cannot be NULL.

OSSL_FUNC_kem_decapsulate() performs the actual decapsulation itself. A previously initialised asymmetric kem context is passed in the ctx parameter. The data to be decapsulated is pointed to by the in parameter which is inlen bytes long. Unless out is NULL, the decapsulated data should be written to the location pointed to by the out parameter. The length of the decapsulated data should be written to *outlen. If out is NULL then the maximum length of the decapsulated data should be written to *outlen.

### Asymmetric Key Encapsulation Parameters
See OSSL_PARAM(3) for further details on the parameters structure used by the OSSL_FUNC_kem_get_ctx_params() and OSSL_FUNC_kem_set_ctx_params() functions.

OSSL_FUNC_kem_get_ctx_params() gets asymmetric kem parameters associated with the given provider side asymmetric kem context ctx and stores them in params. Passing NULL for params should return true.

OSSL_FUNC_kem_set_ctx_params() sets the asymmetric kem parameters associated with the given provider side asymmetric kem context ctx to params. Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

No parameters are currently recognised by built-in asymmetric kem algorithms.

OSSL_FUNC_kem_gettable_ctx_params() and OSSL_FUNC_kem_settable_ctx_params() get a constant OSSL_PARAM(3) array that describes the gettable and settable parameters, i.e. parameters that can be used with OSSL_FUNC_kem_get_ctx_params() and OSSL_FUNC_kem_set_ctx_params() respectively.

## RETURN VALUES
OSSL_FUNC_kem_newctx() and OSSL_FUNC_kem_dupctx() should return the newly created provider side asymmetric kem context, or NULL on failure.

All other functions should return 1 for success or 0 on error.

## SEE ALSO
provider(7)

## HISTORY
The provider KEM interface was introduced in OpenSSL 3.0.

OSSL_FUNC_kem_auth_encapsulate_init() and OSSL_FUNC_kem_auth_decapsulate_init() were added in OpenSSL 3.2.

## COPYRIGHT
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-keyexch

title: provider-keyexch(7ossl)

summary: The keyexch library <\-> provider functions

text:
# provider-keyexch(7ossl)

## NAME
provider-keyexch - The keyexch library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 #include <openssl/core_names.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Context management */
 void *OSSL_FUNC_keyexch_newctx(void *provctx);
 void OSSL_FUNC_keyexch_freectx(void *ctx);
 void *OSSL_FUNC_keyexch_dupctx(void *ctx);
 /* Shared secret derivation */
 int OSSL_FUNC_keyexch_init(void *ctx, void *provkey,
                            const OSSL_PARAM params[]);
 int OSSL_FUNC_keyexch_set_peer(void *ctx, void *provkey);
 int OSSL_FUNC_keyexch_derive(void *ctx, unsigned char *secret, size_t *secretlen,
                              size_t outlen);
 /* Key Exchange parameters */
 int OSSL_FUNC_keyexch_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keyexch_settable_ctx_params(void *ctx,
                                                         void *provctx);
 int OSSL_FUNC_keyexch_get_ctx_params(void *ctx, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keyexch_gettable_ctx_params(void *ctx,
                                                         void *provctx);
```

## DESCRIPTION
This documentation is primarily aimed at provider authors. See provider(7) for further information.

The key exchange (OSSL_OP_KEYEXCH) operation enables providers to implement key exchange algorithms and make them available to applications via EVP_PKEY_derive(3) and other related functions).

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_keyexch_newctx() has these:

```
 typedef void *(OSSL_FUNC_keyexch_newctx_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_keyexch_newctx_fn
     OSSL_FUNC_keyexch_newctx(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_keyexch_newctx                OSSL_FUNC_KEYEXCH_NEWCTX
 OSSL_FUNC_keyexch_freectx               OSSL_FUNC_KEYEXCH_FREECTX
 OSSL_FUNC_keyexch_dupctx                OSSL_FUNC_KEYEXCH_DUPCTX
 OSSL_FUNC_keyexch_init                  OSSL_FUNC_KEYEXCH_INIT
 OSSL_FUNC_keyexch_set_peer              OSSL_FUNC_KEYEXCH_SET_PEER
 OSSL_FUNC_keyexch_derive                OSSL_FUNC_KEYEXCH_DERIVE
 OSSL_FUNC_keyexch_set_ctx_params        OSSL_FUNC_KEYEXCH_SET_CTX_PARAMS
 OSSL_FUNC_keyexch_settable_ctx_params   OSSL_FUNC_KEYEXCH_SETTABLE_CTX_PARAMS
 OSSL_FUNC_keyexch_get_ctx_params        OSSL_FUNC_KEYEXCH_GET_CTX_PARAMS
 OSSL_FUNC_keyexch_gettable_ctx_params   OSSL_FUNC_KEYEXCH_GETTABLE_CTX_PARAMS
```

A key exchange algorithm implementation may not implement all of these functions. In order to be a consistent set of functions a provider must implement OSSL_FUNC_keyexch_newctx, OSSL_FUNC_keyexch_freectx, OSSL_FUNC_keyexch_init and OSSL_FUNC_keyexch_derive. All other functions are optional.

A key exchange algorithm must also implement some mechanism for generating, loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. See provider-keymgmt(7) for further details.

### Context Management Functions
OSSL_FUNC_keyexch_newctx() should create and return a pointer to a provider side structure for holding context information during a key exchange operation. A pointer to this context will be passed back in a number of the other key exchange operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)).

OSSL_FUNC_keyexch_freectx() is passed a pointer to the provider side key exchange context in the ctx parameter. This function should free any resources associated with that context.

OSSL_FUNC_keyexch_dupctx() should duplicate the provider side key exchange context in the ctx parameter and return the duplicate copy.

### Shared Secret Derivation Functions
OSSL_FUNC_keyexch_init() initialises a key exchange operation given a provider side key exchange context in the ctx parameter, and a pointer to a provider key object in the provkey parameter. The params, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_keyexch_set_params(). The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.

OSSL_FUNC_keyexch_set_peer() is called to supply the peer's public key (in the provkey parameter) to be used when deriving the shared secret. It is also passed a previously initialised key exchange context in the ctx parameter. The key object should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)>.

OSSL_FUNC_keyexch_derive() performs the actual key exchange itself by deriving a shared secret. A previously initialised key exchange context is passed in the ctx parameter. The derived secret should be written to the location secret which should not exceed outlen bytes. The length of the shared secret should be written to *secretlen. If secret is NULL then the maximum length of the shared secret should be written to *secretlen.

### Key Exchange Parameters Functions
OSSL_FUNC_keyexch_set_ctx_params() sets key exchange parameters associated with the given provider side key exchange context ctx to params, see "Common Key Exchange parameters". Any parameter settings are additional to any that were previously set. Passing NULL for params should return true.

OSSL_FUNC_keyexch_get_ctx_params() gets key exchange parameters associated with the given provider side key exchange context ctx into params, see "Common Key Exchange parameters". Passing NULL for params should return true.

OSSL_FUNC_keyexch_settable_ctx_params() yields a constant OSSL_PARAM(3) array that describes the settable parameters, i.e. parameters that can be used with OP_signature_set_ctx_params(). If OSSL_FUNC_keyexch_settable_ctx_params() is present, OSSL_FUNC_keyexch_set_ctx_params() must also be present, and vice versa. Similarly, OSSL_FUNC_keyexch_gettable_ctx_params() yields a constant OSSL_PARAM(3) array that describes the gettable parameters, i.e. parameters that can be handled by OP_signature_get_ctx_params(). If OSSL_FUNC_keyexch_gettable_ctx_params() is present, OSSL_FUNC_keyexch_get_ctx_params() must also be present, and vice versa.

Notice that not all settable parameters are also gettable, and vice versa.

### Common Key Exchange parameters
See OSSL_PARAM(3) for further details on the parameters structure used by the OSSL_FUNC_keyexch_set_ctx_params() and OSSL_FUNC_keyexch_get_ctx_params() functions.

Common parameters currently recognised by built-in key exchange algorithms are as follows.

"kdf-type" (OSSL_EXCHANGE_PARAM_KDF_TYPE) <UTF8 string>

Sets or gets the Key Derivation Function type to apply within the associated key exchange ctx.

"kdf-digest" (OSSL_EXCHANGE_PARAM_KDF_DIGEST) <UTF8 string>

Sets or gets the Digest algorithm to be used as part of the Key Derivation Function associated with the given key exchange ctx.

"kdf-digest-props" (OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS) <UTF8 string>

Sets properties to be used upon look up of the implementation for the selected Digest algorithm for the Key Derivation Function associated with the given key exchange ctx.

"kdf-outlen" (OSSL_EXCHANGE_PARAM_KDF_OUTLEN) <unsigned integer>

Sets or gets the desired size for the output of the chosen Key Derivation Function associated with the given key exchange ctx. The length of the "kdf-outlen" parameter should not exceed that of a size_t.

"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string>

Sets the User Key Material to be used as part of the selected Key Derivation Function associated with the given key exchange ctx.

"kdf-ukm" (OSSL_EXCHANGE_PARAM_KDF_UKM) <octet string ptr>

Gets a pointer to the User Key Material to be used as part of the selected Key Derivation Function associated with the given key exchange ctx. Providers usually do not need to support this gettable parameter as its sole purpose is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm() and EVP_PKEY_CTX_get0_dh_kdf_ukm() functions.

## RETURN VALUES
OSSL_FUNC_keyexch_newctx() and OSSL_FUNC_keyexch_dupctx() should return the newly created provider side key exchange context, or NULL on failure.

OSSL_FUNC_keyexch_init(), OSSL_FUNC_keyexch_set_peer(), OSSL_FUNC_keyexch_derive(), OSSL_FUNC_keyexch_set_params(), and OSSL_FUNC_keyexch_get_params() should return 1 for success or 0 on error.

OSSL_FUNC_keyexch_settable_ctx_params() and OSSL_FUNC_keyexch_gettable_ctx_params() should always return a constant OSSL_PARAM(3) array.

## SEE ALSO
provider(7)

## HISTORY
The provider KEYEXCH interface was introduced in OpenSSL 3.0.

## COPYRIGHT
Copyright 2019-2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


provider-keymgmt

title: provider-keymgmt(7ossl)

summary: The KEYMGMT library <\-> provider functions

text:
# provider-keymgmt(7ossl)

## NAME
provider-keymgmt - The KEYMGMT library <-> provider functions

## SYNOPSIS

```
 #include <openssl/core_dispatch.h>
 /*
  * None of these are actual functions, but are displayed like this for
  * the function signatures for functions that are offered as function
  * pointers in OSSL_DISPATCH arrays.
  */
 /* Key object (keydata) creation and destruction */
 void *OSSL_FUNC_keymgmt_new(void *provctx);
 void OSSL_FUNC_keymgmt_free(void *keydata);
 /* Generation, a more complex constructor */
 void *OSSL_FUNC_keymgmt_gen_init(void *provctx, int selection,
                                  const OSSL_PARAM params[]);
 int OSSL_FUNC_keymgmt_gen_set_template(void *genctx, void *template);
 int OSSL_FUNC_keymgmt_gen_set_params(void *genctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_gen_settable_params(void *genctx,
                                                         void *provctx);
 void *OSSL_FUNC_keymgmt_gen(void *genctx, OSSL_CALLBACK *cb, void *cbarg);
 void OSSL_FUNC_keymgmt_gen_cleanup(void *genctx);
 /* Key loading by object reference, also a constructor */
 void *OSSL_FUNC_keymgmt_load(const void *reference, size_t *reference_sz);
 /* Key object information */
 int OSSL_FUNC_keymgmt_get_params(void *keydata, OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_gettable_params(void *provctx);
 int OSSL_FUNC_keymgmt_set_params(void *keydata, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_settable_params(void *provctx);
 /* Key object content checks */
 int OSSL_FUNC_keymgmt_has(const void *keydata, int selection);
 int OSSL_FUNC_keymgmt_match(const void *keydata1, const void *keydata2,
                             int selection);
 /* Discovery of supported operations */
 const char *OSSL_FUNC_keymgmt_query_operation_name(int operation_id);
 /* Key object import and export functions */
 int OSSL_FUNC_keymgmt_import(void *keydata, int selection, const OSSL_PARAM params[]);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types(int selection);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_import_types_ex(void *provctx, int selection);
 int OSSL_FUNC_keymgmt_export(void *keydata, int selection,
                              OSSL_CALLBACK *param_cb, void *cbarg);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types(int selection);
 const OSSL_PARAM *OSSL_FUNC_keymgmt_export_types_ex(void *provctx, int selection);
 /* Key object duplication, a constructor */
 void *OSSL_FUNC_keymgmt_dup(const void *keydata_from, int selection);
 /* Key object validation */
 int OSSL_FUNC_keymgmt_validate(const void *keydata, int selection, int checktype);
```

## DESCRIPTION
The KEYMGMT operation doesn't have much public visibility in OpenSSL libraries, it's rather an internal operation that's designed to work in tandem with operations that use private/public key pairs.

Because the KEYMGMT operation shares knowledge with the operations it works with in tandem, they must belong to the same provider. The OpenSSL libraries will ensure that they do.

The primary responsibility of the KEYMGMT operation is to hold the provider side key data for the OpenSSL library EVP_PKEY structure.

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) arrays that are returned by the provider's provider_query_operation() function (see "Provider Functions" in provider-base(7)).

All these "functions" have a corresponding function type definition named OSSL_FUNC_{name}_fn, and a helper function to retrieve the function pointer from a OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_keymgmt_new() has these:

```
 typedef void *(OSSL_FUNC_keymgmt_new_fn)(void *provctx);
 static ossl_inline OSSL_FUNC_keymgmt_new_fn
     OSSL_FUNC_keymgmt_new(const OSSL_DISPATCH *opf);
```

OSSL_DISPATCH(3) arrays are indexed by numbers that are provided as macros in openssl-core_dispatch.h(7), as follows:

```
 OSSL_FUNC_keymgmt_new                  OSSL_FUNC_KEYMGMT_NEW
 OSSL_FUNC_keymgmt_free                 OSSL_FUNC_KEYMGMT_FREE
 OSSL_FUNC_keymgmt_gen_init             OSSL_FUNC_KEYMGMT_GEN_INIT
 OSSL_FUNC_keymgmt_gen_set_template     OSSL_FUNC_KEYMGMT_GEN_SET_TEMPLATE
 OSSL_FUNC_keymgmt_gen_set_params       OSSL_FUNC_KEYMGMT_GEN_SET_PARAMS
 OSSL_FUNC_keymgmt_gen_settable_params  OSSL_FUNC_KEYMGMT_GEN_SETTABLE_PARAMS
 OSSL_FUNC_keymgmt_gen                  OSSL_FUNC_KEYMGMT_GEN
 OSSL_FUNC_keymgmt_gen_cleanup          OSSL_FUNC_KEYMGMT_GEN_CLEANUP
 OSSL_FUNC_keymgmt_load                 OSSL_FUNC_KEYMGMT_LOAD
 OSSL_FUNC_keymgmt_get_params           OSSL_FUNC_KEYMGMT_GET_PARAMS
 OSSL_FUNC_keymgmt_gettable_params      OSSL_FUNC_KEYMGMT_GETTABLE_PARAMS
 OSSL_FUNC_keymgmt_set_params           OSSL_FUNC_KEYMGMT_SET_PARAMS
 OSSL_FUNC_keymgmt_settable_params      OSSL_FUNC_KEYMGMT_SETTABLE_PARAMS
 OSSL_FUNC_keymgmt_query_operation_name OSSL_FUNC_KEYMGMT_QUERY_OPERATION_NAME
 OSSL_FUNC_keymgmt_has                  OSSL_FUNC_KEYMGMT_HAS
 OSSL_FUNC_keymgmt_validate             OSSL_FUNC_KEYMGMT_VALIDATE
 OSSL_FUNC_keymgmt_match                OSSL_FUNC_KEYMGMT_MATCH
 OSSL_FUNC_keymgmt_import               OSSL_FUNC_KEYMGMT_IMPORT
 OSSL_FUNC_keymgmt_import_types         OSSL_FUNC_KEYMGMT_IMPORT_TYPES
 OSSL_FUNC_keymgmt_import_types_ex      OSSL_FUNC_KEYMGMT_IMPORT_TYPES_EX
 OSSL_FUNC_keymgmt_export               OSSL_FUNC_KEYMGMT_EXPORT
 OSSL_FUNC_keymgmt_export_types         OSSL_FUNC_KEYMGMT_EXPORT_TYPES
 OSSL_FUNC_keymgmt_export_types_ex      OSSL_FUNC_KEYMGMT_EXPORT_TYPES_EX
 OSSL_FUNC_keymgmt_dup                  OSSL_FUNC_KEYMGMT_DUP
```

### Key Objects
A key object is a collection of data for an asymmetric key, and is represented as keydata in this manual.

The exact contents of a key object are defined by the provider, and it is assumed that different operations in one and the same provider use the exact same structure to represent this collection of data, so that for example, a key object that has been created using the KEYMGMT interface that we document here can be passed as is to other provider operations, such as OP_signature_sign_init() (see provider-signature(7)).

With some of the KEYMGMT functions, it's possible to select a specific subset of data to handle, governed by the bits in a selection indicator. The bits are:

OSSL_KEYMGMT_SELECT_PRIVATE_KEY

Indicating that the private key data in a key object should be considered.

OSSL_KEYMGMT_SELECT_PUBLIC_KEY

Indicating that the public key data in a key object should be considered.

OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS

Indicating that the domain parameters in a key object should be considered.

OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS

Indicating that other parameters in a key object should be considered. Other parameters are key parameters that don't fit any other classification. In other words, this particular selector bit works as a last resort bit bucket selector.

Some selector bits have also been combined for easier use:

OSSL_KEYMGMT_SELECT_ALL_PARAMETERS

Indicating that all key object parameters should be considered, regardless of their more granular classification. This is a combination of OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS and OSSL_KEYMGMT_SELECT_OTHER_PARAMETERS.

OSSL_KEYMGMT_SELECT_KEYPAIR

Indicating that both the whole key pair in a key object should be considered, i.e. the combination of public and private key. This is a combination of OSSL_KEYMGMT_SELECT_PRIVATE_KEY and OSSL_KEYMGMT_SELECT_PUBLIC_KEY.

OSSL_KEYMGMT_SELECT_ALL

Indicating that everything in a key object should be considered.

The exact interpretation of those bits or how they combine is left to each function where you can specify a selector.

It's left to the provider implementation to decide what is reasonable to do with regards to received selector bits and how to do it. Among others, an implementation of OSSL_FUNC_keymgmt_match() might opt to not compare the private half if it has compared the public half, since a match of one half implies a match of the other half.

### Constructing and Destructing Functions
OSSL_FUNC_keymgmt_new() should create a provider side key object. The provider context provctx is passed and may be incorporated in the key object, but that is not mandatory.

OSSL_FUNC_keymgmt_free() should free the passed keydata.

OSSL_FUNC_keymgmt_gen_init(), OSSL_FUNC_keymgmt_gen_set_template(), OSSL_FUNC_keymgmt_gen_set_params(), OSSL_FUNC_keymgmt_gen_settable_params(), OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_gen_cleanup() work together as a more elaborate context based key object constructor.

OSSL_FUNC_keymgmt_gen_init() should create the key object generation context and initialize it with selections, which will determine what kind of contents the key object to be generated should get. The params, if not NULL, should be set on the context in a manner similar to using OSSL_FUNC_keymgmt_set_params().

OSSL_FUNC_keymgmt_gen_set_template() should add template to the context genctx. The template is assumed to be a key object constructed with the same KEYMGMT, and from which content that the implementation chooses can be used as a template for the key object to be generated. Typically, the generation of a DSA or DH key would get the domain parameters from this template.

OSSL_FUNC_keymgmt_gen_set_params() should set additional parameters from params in the key object generation context genctx.

OSSL_FUNC_keymgmt_gen_settable_params() should return a constant array of descriptor OSSL_PARAM(3), for parameters that OSSL_FUNC_keymgmt_gen_set_params() can handle.

OSSL_FUNC_keymgmt_gen() should perform the key object generation itself, and return the result. The callback cb should be called at regular intervals with indications on how the key object generation progresses.

OSSL_FUNC_keymgmt_gen_cleanup() should clean up and free the key object generation context genctx

OSSL_FUNC_keymgmt_load() creates a provider side key object based on a reference object with a size of reference_sz bytes, that only the provider knows how to interpret, but that may come from other operations. Outside the provider, this reference is simply an array of bytes.

At least one of OSSL_FUNC_keymgmt_new(), OSSL_FUNC_keymgmt_gen() and OSSL_FUNC_keymgmt_load() are mandatory, as well as OSSL_FUNC_keymgmt_free() and OSSL_FUNC_keymgmt_has(). Additionally, if OSSL_FUNC_keymgmt_gen() is present, OSSL_FUNC_keymgmt_gen_init() and OSSL_FUNC_keymgmt_gen_cleanup() must be present as well.

### Key Object Information Functions
OSSL_FUNC_keymgmt_get_params() should extract information data associated with the given keydata, see "Common Information Parameters".

OSSL_FUNC_keymgmt_gettable_params() should return a constant array of descriptor OSSL_PARAM(3), for parameters that OSSL_FUNC_keymgmt_get_params() can handle.

If OSSL_FUNC_keymgmt_gettable_params() is present, OSSL_FUNC_keymgmt_get_params() must also be present, and vice versa.

OSSL_FUNC_keymgmt_set_params() should update information data associated with the given keydata, see "Common Information Parameters".

OSSL_FUNC_keymgmt_settable_params() should return a constant array of descriptor OSSL_PARAM(3), for parameters that OSSL_FUNC_keymgmt_set_params() can handle.

If OSSL_FUNC_keymgmt_settable_params() is present, OSSL_FUNC_keymgmt_set_params() must also be present, and vice versa.

### Key Object Checking Functions
OSSL_FUNC_keymgmt_query_operation_name() should return the name of the supported algorithm for the operation operation_id. This is similar to provider_query_operation() (see provider-base(7)), but only works as an advisory. If this function is not present, or returns NULL, the caller is free to assume that there's an algorithm from the same provider, of the same name as the one used to fetch the keymgmt and try to use that.

OSSL_FUNC_keymgmt_has() should check whether the given keydata contains the subsets of data indicated by the selector. A combination of several selector bits must consider all those subsets, not just one. An implementation is, however, free to consider an empty subset of data to still be a valid subset. For algorithms where some selection is not meaningful such as OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS for RSA keys the function should just return 1 as the selected subset is not really missing in the key.

OSSL_FUNC_keymgmt_validate() should check if the keydata contains valid data subsets indicated by selection. Some combined selections of data subsets may cause validation of the combined data. For example, the combination of OSSL_KEYMGMT_SELECT_PRIVATE_KEY and OSSL_KEYMGMT_SELECT_PUBLIC_KEY (or OSSL_KEYMGMT_SELECT_KEYPAIR for short) is expected to check that the pairwise consistency of keydata is valid. The checktype parameter controls what type of check is performed on the subset of data. Two types of check are defined: OSSL_KEYMGMT_VALIDATE_FULL_CHECK and OSSL_KEYMGMT_VALIDATE_QUICK_CHECK. The interpretation of how much checking is performed in a full check versus a quick check is key type specific. Some providers may have no distinction between a full check and a quick check. For algorithms where some selection is not meaningful such as OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS for RSA keys the function should just return 1 as there is nothing to validate for that selection.

OSSL_FUNC_keymgmt_match() should check if the data subset indicated by selection in keydata1 and keydata2 match. It is assumed that the caller has ensured that keydata1 and keydata2 are both owned by the implementation of this function.

### Key Object Import, Export and Duplication Functions
OSSL_FUNC_keymgmt_import() should import data indicated by selection into keydata with values taken from the OSSL_PARAM(3) array params.

OSSL_FUNC_keymgmt_export() should extract values indicated by selection from keydata, create an OSSL_PARAM(3) array with them and call param_cb with that array as well as the given cbarg.

OSSL_FUNC_keymgmt_import_types() and OSSL_FUNC_keymgmt_import_types_ex() should return a constant array of descriptor OSSL_PARAM(3) for data indicated by selection, for parameters that OSSL_FUNC_keymgmt_import() can handle. Either OSSL_FUNC_keymgmt_import_types() or OSSL_FUNC_keymgmt_import_types_ex(), must be implemented, if OSSL_FUNC_keymgmt_import_types_ex() is implemented, then it is preferred over OSSL_FUNC_keymgmt_import_types(). Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 must continue to implement OSSL_FUNC_keymgmt_import_types().

OSSL_FUNC_keymgmt_export_types() and OSSL_FUNC_keymgmt_export_types_ex() should return a constant array of descriptor OSSL_PARAM(3) for data indicated by selection, that the OSSL_FUNC_keymgmt_export() callback can expect to receive. Either OSSL_FUNC_keymgmt_export_types() or OSSL_FUNC_keymgmt_export_types_ex(), must be implemented, if OSSL_FUNC_keymgmt_export_types_ex() is implemented, then it is preferred over OSSL_FUNC_keymgmt_export_types(). Providers that are supposed to be backward compatible with OpenSSL 3.0 or 3.1 must continue to implement OSSL_FUNC_keymgmt_export_types().

OSSL_FUNC_keymgmt_dup() should duplicate data subsets indicated by selection or the whole key data keydata_from and create a new provider side key object with the data.

### Common Information Parameters
See OSSL_PARAM(3) for further details on the parameters structure.

Common information parameters currently recognised by all built-in keymgmt algorithms are as follows:

"bits" (OSSL_PKEY_PARAM_BITS) <integer>

The value should be the cryptographic length of the cryptosystem to which the key belongs, in bits. The definition of cryptographic length is specific to the key cryptosystem.

"max-size" (OSSL_PKEY_PARAM_MAX_SIZE) <integer>

The value should be the maximum size that a caller should allocate to safely store a signature (called sig in provider-signature(7)), the result of asymmetric encryption / decryption (out in provider-asym_cipher(7), a derived secret (secret in provider-keyexch(7), and similar data). Providers need to implement this parameter in order to properly support various use cases such as CMS signing.

Because an EVP_KEYMGMT method is always tightly bound to another method (signature, asymmetric cipher, key exchange, ...) and must be of the same provider, this number only needs to be synchronised with the dimensions handled in the rest of the same provider.

"security-bits" (OSSL_PKEY_PARAM_SECURITY_BITS) <integer>

The value should be the number of security bits of the given key. Bits of security is defined in SP800-57.

"mandatory-digest" (OSSL_PKEY_PARAM_MANDATORY_DIGEST) <UTF8 string>

If there is a mandatory digest for performing a signature operation with keys from this keymgmt, this parameter should get its name as value. When EVP_PKEY_get_default_digest_name() queries this parameter and it's filled in by the implementation, its return value will be 2.

If the keymgmt implementation fills in the value "" or "UNDEF", EVP_PKEY_get_default_digest_name(3) will place the string "UNDEF" into its argument mdname. This signifies that no digest should be specified with the corresponding signature operation.

"default-digest" (OSSL_PKEY_PARAM_DEFAULT_DIGEST) <UTF8 string>

If there is a default digest for performing a signature operation with keys from this keymgmt, this parameter should get its name as value. When EVP_PKEY_get_default_digest_name(3) queries this parameter and it's filled in by the implementation, its return value will be 1. Note that if OSSL_PKEY_PARAM_MANDATORY_DIGEST is responded to as well, EVP_PKEY_get_default_digest_name(3) ignores the response to this parameter.

If the keymgmt implementation fills in the value "" or "UNDEF", EVP_PKEY_get_default_digest_name(3) will place the string "UNDEF" into its argument mdname. This signifies that no digest has to be specified with the corresponding signature operation, but may be specified as an option.

## RETURN VALUES
OSSL_FUNC_keymgmt_new() and OSSL_FUNC_keymgmt_dup() should return a valid reference to the newly created provider side key object, or NULL on failure.

OSSL_FUNC_keymgmt_import(), OSSL_FUNC_keymgmt_export(), OSSL_FUNC_keymgmt_get_params() and OSSL_FUNC_keymgmt_set_params() should return 1 for success or 0 on error.

OSSL_FUNC_keymgmt_validate() should return 1 on successful validation, or 0 on failure.

OSSL_FUNC_keymgmt_has() should return 1 if all the selected data subsets are contained in the given keydata or 0 otherwise.

OSSL_FUNC_keymgmt_query_operation_name() should return a pointer to a string matching the requested operation, or NULL if the same name used to fetch the keymgmt applies.

OSSL_FUNC_keymgmt_gettable_params() and OSSL_FUNC_keymgmt_settable_params() OSSL_FUNC_keymgmt_import_types(), OSSL_FUNC_keymgmt_import_types_ex(), OSSL_FUNC_keymgmt_export_types(), OSSL_FUNC_keymgmt_export_types_ex() should always return a constant OSSL_PARAM(3) array.

## SEE ALSO
EVP_PKEY_get_size(3), EVP_PKEY_get_bits(3), EVP_PKEY_get_security_bits(3), provider(7), EVP_PKEY-X25519(7), EVP_PKEY-X448(7), EVP_PKEY-ED25519(7), EVP_PKEY-ED448(7), EVP_PKEY-EC(7), EVP_PKEY-RSA(7), EVP_PKEY-DSA(7), EVP_PKEY-DH(7)

## HISTORY
The KEYMGMT interface was introduced in OpenSSL 3.0.

Functions OSSL_FUNC_keymgmt_import_types_ex(), and OSSL_FUNC_keymgmt_export_types_ex() were added with OpenSSL 3.2.

## COPYRIGHT
Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.