PROVIDER-ASYM_CIPHER(7ossl)

📦

version 3.5.9 · 8 versions

3.5.9 · alpine 3.23, alpine 3.24 (latest)
3.5.9 · centos-stream 9
3.5.9 · centos-stream 10
3.5.9 · alpine 3.22
3.5.8 · fedora 43
3.5.1 · fedora 43
3.5.9 · fedora 43, fedora 44
3.5.5 · fedora 44

💖 NAME 💖

provider-asym_cipher — bestie, this is the asym_cipher library <-> provider functions page, straight out of the OpenSSL 7ossl manual set ✨

✨ SYNOPSIS ✨

okay so first things first, you gotta pull in the headers, no cap:

#include <openssl/core_dispatch.h>
#include <openssl/core_names.h>

and now the big vibe check, the disclaimer that saves you from a whole crisis:

/*
 * 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.
 */

like, read that again bestie. 🫶 these are not real functions you can just call — they're signatures for the function pointers you'll find chilling inside OSSL_DISPATCH arrays. it's giving casting call, not actual actors. iykyk.

🎀 Context management 🎀

the whole "who am i, where am i" of it all — setup, cleanup, and the duplicate:

void *OSSL_FUNC_asym_cipher_newctx(void *provctx);
void OSSL_FUNC_asym_cipher_freectx(void *ctx);
void *OSSL_FUNC_asym_cipher_dupctx(void *ctx);

OSSL_FUNC_asym_cipher_newctx — makes a fresh new context out of provctx, main character energy from the jump 💅
OSSL_FUNC_asym_cipher_freectx — yeets the context, ctx gets cleaned up, we love a tidy exit
OSSL_FUNC_asym_cipher_dupctx — copy of ctx, because sometimes you need two of her 🌸

🔥 Encryption 🔥

locking it in — init first, then the actual encrypt:

int OSSL_FUNC_asym_cipher_encrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_encrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

OSSL_FUNC_asym_cipher_encrypt_init — sets up ctx with provkey and the params array, the pre-game ritual before anything spicy happens ⭐
OSSL_FUNC_asym_cipher_encrypt — the moment. ctx, out, outlen, outsize, in, inlen, all accounted for, encrypted, done, periodt 💀

🦋 Decryption 🦋

same energy, opposite direction:

int OSSL_FUNC_asym_cipher_decrypt_init(void *ctx, void *provkey,
                                       const OSSL_PARAM params[]);
int OSSL_FUNC_asym_cipher_decrypt(void *ctx, unsigned char *out, size_t *outlen,
                                  size_t outsize, const unsigned char *in,
                                  size_t inlen);

OSSL_FUNC_asym_cipher_decrypt_init — hands ctx its provkey and params, the reverse-direction warm-up 🧚
OSSL_FUNC_asym_cipher_decrypt — takes in/inlen, drops the result into out/outlen with outsize as the ceiling, iconic behaviour honestly 👑

🌈 Asymmetric Cipher parameters 🌈

the settings girlies — gettable params, settable params, and the lists that tell you what's even on the menu:

int OSSL_FUNC_asym_cipher_get_ctx_params(void *ctx, OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_gettable_ctx_params(void *ctx, void *provctx);
int OSSL_FUNC_asym_cipher_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
const OSSL_PARAM *OSSL_FUNC_asym_cipher_settable_ctx_params(void *ctx, void *provctx);

OSSL_FUNC_asym_cipher_get_ctx_params — reads the params off ctx into the params array, respectfully snooping 🔍
OSSL_FUNC_asym_cipher_gettable_ctx_params — returns the const OSSL_PARAM * list of what you're allowed to get, taking ctx and provctx, so nobody's guessing ✨
OSSL_FUNC_asym_cipher_set_ctx_params — writes the params array into ctx, the glow-up button 💅
OSSL_FUNC_asym_cipher_settable_ctx_params — returns the const OSSL_PARAM * list of what you're allowed to set, ctx and provctx in hand, no surprises 💖

💅 DESCRIPTION 💅

Okay bestie, listen up — this documentation is primarily aimed at provider authors. Like, if you're just out here using OpenSSL, that's a different vibe. Check out provider(7) for the full rundown, iykyk.

The asymmetric cipher operation — that's OSSL_OP_ASYM_CIPHER — is literally what lets providers implement asymmetric cipher algorithms and put them on the menu for applications, via the API functions EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3) and other related functions. 🎀

So. All the "functions" we're talking about here get passed as function pointers between libcrypto and the provider, inside OSSL_DISPATCH(3) arrays, which come through OSSL_ALGORITHM(3) arrays that your provider's provider_query_operation() function hands back (peep "Provider Functions" in provider-base(7)).

Every single one of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a helper to scoop the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. Example time, because yes:

typedef void *(OSSL_FUNC_asym_cipher_newctx_fn)(void *provctx);
static ossl_inline OSSL_FUNC_asym_cipher_newctx_fn
    OSSL_FUNC_asym_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), and the whole mapping is giving:

OSSL_FUNC_asym_cipher_newctx               OSSL_FUNC_ASYM_CIPHER_NEWCTX
OSSL_FUNC_asym_cipher_freectx              OSSL_FUNC_ASYM_CIPHER_FREECTX
OSSL_FUNC_asym_cipher_dupctx               OSSL_FUNC_ASYM_CIPHER_DUPCTX

OSSL_FUNC_asym_cipher_encrypt_init         OSSL_FUNC_ASYM_CIPHER_ENCRYPT_INIT
OSSL_FUNC_asym_cipher_encrypt              OSSL_FUNC_ASYM_CIPHER_ENCRYPT

OSSL_FUNC_asym_cipher_decrypt_init         OSSL_FUNC_ASYM_CIPHER_DECRYPT_INIT
OSSL_FUNC_asym_cipher_decrypt              OSSL_FUNC_ASYM_CIPHER_DECRYPT

OSSL_FUNC_asym_cipher_get_ctx_params       OSSL_FUNC_ASYM_CIPHER_GET_CTX_PARAMS
OSSL_FUNC_asym_cipher_gettable_ctx_params  OSSL_FUNC_ASYM_CIPHER_GETTABLE_CTX_PARAMS
OSSL_FUNC_asym_cipher_set_ctx_params       OSSL_FUNC_ASYM_CIPHER_SET_CTX_PARAMS
OSSL_FUNC_asym_cipher_settable_ctx_params  OSSL_FUNC_ASYM_CIPHER_SETTABLE_CTX_PARAMS

Now, real talk: an asymmetric cipher algorithm implementation may not implement all of these functions. No cap. But to be a consistent set of functions, a provider must implement OSSL_FUNC_asym_cipher_newctx and OSSL_FUNC_asym_cipher_freectx. It must also implement both of OSSL_FUNC_asym_cipher_encrypt_init and OSSL_FUNC_asym_cipher_encrypt, or both of OSSL_FUNC_asym_cipher_decrypt_init and OSSL_FUNC_asym_cipher_decrypt. OSSL_FUNC_asym_cipher_get_ctx_params is optional, but if it's there then OSSL_FUNC_asym_cipher_gettable_ctx_params has to be there too. Same energy for OSSL_FUNC_asym_cipher_set_ctx_params — optional, but if it's present then so must OSSL_FUNC_asym_cipher_settable_ctx_params. They're a package deal, periodt. 💅

Also, an asymmetric cipher algorithm must implement some mechanism for generating, loading or importing keys via the key management (OSSL_OP_KEYMGMT) operation. See provider-keymgmt(7) for the details, bestie.

✨ Context Management Functions ✨

OSSL_FUNC_asym_cipher_newctx() — should create and return a pointer to a provider side structure for holding context information during an asymmetric cipher operation. That pointer gets passed back in a bunch of the other asymmetric cipher operation function calls. The parameter provctx is the provider context generated during provider initialisation (see provider(7)). 🫶
OSSL_FUNC_asym_cipher_freectx() — gets passed a pointer to the provider side asymmetric cipher context in the ctx parameter. This function should free any resources associated with that context. Clean up your room, babe. 🧹
OSSL_FUNC_asym_cipher_dupctx() — should duplicate the provider side asymmetric cipher context in the ctx parameter and return the duplicate copy. Twin energy. 👯

🔥 Encryption Functions 🔥

OSSL_FUNC_asym_cipher_encrypt_init() initialises a context for an asymmetric encryption, given a provider side asymmetric cipher 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_asym_cipher_set_ctx_params(). And that key object? It should have been previously generated, loaded or imported into the provider using the key management (OSSL_OP_KEYMGMT) operation (see provider-keymgmt(7)). No shortcuts. ⭐

OSSL_FUNC_asym_cipher_encrypt() performs the actual encryption itself. Fr fr, this is the main character. A previously initialised asymmetric cipher context is passed in the ctx parameter. The data to be encrypted is pointed to by the in parameter, which is inlen bytes long. Unless out is NULL, the encrypted data should be written to the location pointed to by the out parameter and it should not exceed outsize bytes in length. The length of the encrypted data should be written to *outlen. And if out is NULL? Then the maximum length of the encrypted data should be written to *outlen. 🦋

🌸 Decryption Functions 🌸

OSSL_FUNC_asym_cipher_decrypt_init() initialises a context for an asymmetric decryption, given a provider side asymmetric cipher 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_asym_cipher_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)). Yeah, same drill as encryption — the keys gotta come from somewhere legit. 🗝️

OSSL_FUNC_asym_cipher_decrypt() performs the actual decryption itself. A previously initialised asymmetric cipher context is passed in the ctx parameter. The data to be decrypted is pointed to by the in parameter, which is inlen bytes long. Unless out is NULL, the decrypted data should be written to the location pointed to by the out parameter and it should not exceed outsize bytes in length. The length of the decrypted data should be written to *outlen. If out is NULL then the maximum length of the decrypted data should be written to *outlen. 💜

🎀 Asymmetric Cipher Parameters 🎀

See OSSL_PARAM(3) for the full tea on the parameters structure that OSSL_FUNC_asym_cipher_get_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params() use. 📖

OSSL_FUNC_asym_cipher_get_ctx_params() — gets asymmetric cipher parameters associated with the given provider side asymmetric cipher context ctx and stores them in params. Passing NULL for params should return true.
OSSL_FUNC_asym_cipher_set_ctx_params() — sets the asymmetric cipher parameters associated with the given provider side asymmetric cipher context ctx to params. Any parameter settings are additional to any that were previously set — it stacks, it doesn't replace. Passing NULL for params should return true.

Parameters currently recognised by built-in asymmetric cipher algorithms are as follows. Not all parameters are relevant to, or are understood by, all asymmetric cipher algorithms — so don't come for me if your algorithm ghosts one of them. 🙈

"pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 string> OR <integer> — the type of padding to be used. The interpretation of this value will depend on the algorithm in use. Choose wisely. 🛋️
"digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string> — gets or sets the name of the OAEP digest algorithm used when OAEP padding is in use.
"digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string> — gets or sets the name of the digest algorithm used by the algorithm (where applicable).
"digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string> — gets or sets the properties to use when fetching the OAEP digest algorithm.
"digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string> — gets or sets the properties to use when fetching the cipher digest algorithm.
"mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string> — gets or sets the name of the MGF1 digest algorithm used when OAEP or PSS padding is in use.
"mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 string> — gets or sets the properties to use when fetching the MGF1 digest algorithm.
"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string ptr> — gets the OAEP label used when OAEP padding is in use.
"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string> — sets the OAEP label used when OAEP padding is in use.
"tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer> — the TLS protocol version first requested by the client.
"tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer> — the negotiated TLS protocol version.
"implicit-rejection" (OSSL_ASYM_CIPHER_PARAM_IMPLICIT_REJECTION) <unsigned integer> — gets or sets the use of the implicit rejection mechanism for RSA PKCS#1 v1.5 decryption. When set (non zero value), the decryption API will return a deterministically random value if the PKCS#1 v1.5 padding check fails. This makes exploitation of the Bleichenbacher significantly harder, even if the code using the RSA decryption API is not implemented in side-channel free manner. Set by default in OpenSSL providers. Lowkey a big deal — this is the security glow-up. 🔥

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_ASYM_CIPHER_PARAM_FIPS_APPROVED_INDICATOR) <integer> — a getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling either OSSL_FUNC_asym_cipher_encrypt() or OSSL_FUNC_asym_cipher_decrypt(). It may return 0 if "key-check" is set to 0. ⭐
"key-check" (OSSL_ASYM_CIPHER_PARAM_FIPS_KEY_CHECK) <integer> — if required, this parameter should be set using either OSSL_FUNC_asym_cipher_encrypt_init() or OSSL_FUNC_asym_cipher_decrypt_init(). The default value of 1 causes an error during the init if the key is not FIPS approved (e.g. the key has a security strength of less than 112 bits). Setting this to 0 will ignore the error and set the approved "fips-indicator" to 0.

🚨 Heads up bestie: this option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0. Like, that's the whole trade-off. You've been warned. 💀

And finally: OSSL_FUNC_asym_cipher_gettable_ctx_params() and OSSL_FUNC_asym_cipher_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_asym_cipherget_ctx_params() and OSSL_FUNC_asym_cipher_set_ctx_params() respectively. That's your menu of what's even on the table. 📋

📜 COPYRIGHT 📜

okay bestie, legal bit time — stay with me, it's short 💖

that's the whole squad holding it down, no cap 👑

and here's the licensing tea ☕ — this file is Licensed under the Apache License 2.0 (the "License"), and like… you literally may not use this file except in compliance with the License. that's not me being dramatic, that's just how it is 🙈

if you want the full receipt (and honestly you should read it, it's giving responsible main character energy), you can grab a copy in the file LICENSE in the source distribution, or hit up:

<https://www.openssl.org/source/license.html>

that URL is the plug 🔗✨

and that's a wrap on the whole page, bestie!! 🎀🦋 this little legend came from 3.5.9 and it's dated 2026-09-29 — screenshot it, bookmark it, tattoo it on your forearm, whatever works for you 💅💜

go forth and configure your OSSL_ASYM_CIPHER providers like the icon you are 🌈⭐

📦 where this page comes from

alpine 3.23: openssl-doc 3.5.9-r0 · Apache-2.0
alpine 3.24: openssl-doc 3.5.9-r0 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms