Sortix volatile manual

This manual documents Sortix volatile, a development build that has not been officially released. You can instead view this document in the latest official manual.

EVP_PKEY_METH_NEW(3)

Library Functions Manual

EVP_PKEY_METH_NEW(3)

NAME

EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, EVP_PKEY_meth_add0, EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, EVP_PKEY_meth_set_check, EVP_PKEY_meth_set_public_check, EVP_PKEY_meth_set_param_check, EVP_PKEY_CTX_get_data, EVP_PKEY_CTX_set_data — manipulate an EVP_PKEY_METHOD structure

SYNOPSIS

#include <openssl/evp.h>

EVP_PKEY_METHOD *
EVP_PKEY_meth_new(int id, int flags);

void
EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth);

void
EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src);

const EVP_PKEY_METHOD *
EVP_PKEY_meth_find(int type);

int
EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth);

void
EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth, int (*init)(EVP_PKEY_CTX *ctx));

void
EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth, int (*copy)(EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src));

void
EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth, void (*cleanup)(EVP_PKEY_CTX *ctx));

void
EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth, int (*paramgen_init)(EVP_PKEY_CTX *ctx), int (*paramgen)(EVP_PKEY_CTX *ctx, EVP_PKEY *pkey));

void
EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth, int (*keygen_init)(EVP_PKEY_CTX *ctx), int (*keygen)(EVP_PKEY_CTX *ctx, EVP_PKEY *pkey));

void
EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth, int (*sign_init)(EVP_PKEY_CTX *ctx), int (*sign)(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, const unsigned char *tbs, size_t tbslen));

void
EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth, int (*verify_init)(EVP_PKEY_CTX *ctx), int (*verify)(EVP_PKEY_CTX *ctx, const unsigned char *sig, size_t siglen, const unsigned char *tbs, size_t tbslen));

void
EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth, int (*verify_recover_init)(EVP_PKEY_CTX *ctx), int (*verify_recover)(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, const unsigned char *tbs, size_t tbslen));

void
EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth, int (*signctx_init)(EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx), int (*signctx)(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, EVP_MD_CTX *mctx));

void
EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth, int (*verifyctx_init)(EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx), int (*verifyctx)(EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen, EVP_MD_CTX *mctx));

void
EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth, int (*encrypt_init)(EVP_PKEY_CTX *ctx), int (*encryptfn)(EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, const unsigned char *in, size_t inlen));

void
EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth, int (*decrypt_init)(EVP_PKEY_CTX *ctx), int (*decrypt)(EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, const unsigned char *in, size_t inlen));

void
EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth, int (*derive_init)(EVP_PKEY_CTX *ctx), int (*derive)(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen));

void
EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth, int (*ctrl)(EVP_PKEY_CTX *ctx, int type, int p1, void *p2), int (*ctrl_str)(EVP_PKEY_CTX *ctx, const char *type, const char *value));

void
EVP_PKEY_meth_set_check(EVP_PKEY_METHOD *pmeth, int (*check)(EVP_PKEY *pkey));

void
EVP_PKEY_meth_set_public_check(EVP_PKEY_METHOD *pmeth, int (*public_check)(EVP_PKEY *pkey));

void
EVP_PKEY_meth_set_param_check(EVP_PKEY_METHOD *pmeth, int (*param_check)(EVP_PKEY *pkey));

void *
EVP_PKEY_CTX_get_data(EVP_PKEY_CTX *ctx);

void
EVP_PKEY_CTX_set_data(EVP_PKEY_CTX *ctx, void *data);

DESCRIPTION

The EVP_PKEY_METHOD structure holds a set of methods for a specific public key cryptographic algorithm. Those methods perform tasks such as generating keys, signing, verifying, encrypting, decrypting, and so on.

There are two places where the EVP_PKEY_METHOD objects are stored: one is a built-in static array representing the standard methods for different algorithms, and the other one is a stack of user-defined application-specific methods, which can be manipulated with EVP_PKEY_meth_add0().

The EVP_PKEY_METHOD objects are usually referenced by EVP_PKEY_CTX objects.

Methods

The methods implement the particular public key algorithm represented by the EVP_PKEY_CTX object.

int (*init)(EVP_PKEY_CTX *ctx)
int (*copy)(EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src)
void (*cleanup)(EVP_PKEY_CTX *ctx)

The init() method is called by EVP_PKEY_CTX_new(3) and EVP_PKEY_CTX_new_id(3) to initialize the algorithm-specific data when a new EVP_PKEY_CTX is created. The cleanup() method is called by EVP_PKEY_CTX_free(3) when an EVP_PKEY_CTX is freed. The copy() method is called by EVP_PKEY_CTX_dup(3) when an EVP_PKEY_CTX is duplicated.

int (*paramgen_init)(EVP_PKEY_CTX *ctx)
int (*paramgen)(EVP_PKEY_CTX *ctx, EVP_PKEY *pkey)

The paramgen_init() and paramgen() methods deal with key parameter generation. They are called by EVP_PKEY_paramgen_init(3) and EVP_PKEY_paramgen(3) to handle the parameter generation process.

int (*keygen_init)(EVP_PKEY_CTX *ctx)
int (*keygen)(EVP_PKEY_CTX *ctx, EVP_PKEY *pkey)

The keygen_init() and keygen() methods are used to generate a key for the specified algorithm. They are called by EVP_PKEY_keygen_init(3) and EVP_PKEY_keygen(3).

int (*sign_init)(EVP_PKEY_CTX *ctx)
int (*sign)(
EVP_PKEY_CTX *ctx,
unsigned char *sig,
size_t *siglen,
const unsigned char *tbs,
size_t tbslen);

The sign_init() and sign() methods are used to generate the signature of a piece of data using a private key. They are called by EVP_PKEY_sign_init(3) and EVP_PKEY_sign(3).

int (*verify_init)(EVP_PKEY_CTX *ctx)
int (*verify)(
EVP_PKEY_CTX *ctx,
const unsigned char *sig,
size_t siglen,
const unsigned char *tbs,
size_t tbslen);

The verify_init() and verify() methods are used to verify whether a signature is valid. They are called by EVP_PKEY_verify_init(3) and EVP_PKEY_verify(3).

int (*verify_recover_init)(EVP_PKEY_CTX *ctx)
int (*verify_recover)(
EVP_PKEY_CTX *ctx,
unsigned char *rout,
size_t *routlen,
const unsigned char *sig,
size_t siglen);

The verify_recover_init() and verify_recover() methods are used to verify a signature and then recover the digest from the signature (for instance, a signature that was generated by the RSA signing algorithm). They are called by EVP_PKEY_verify_recover_init(3) and EVP_PKEY_verify_recover(3).

int (*signctx_init)(EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx)
int (*signctx)(
EVP_PKEY_CTX *ctx,
unsigned char *sig,
size_t *siglen,
EVP_MD_CTX *mctx);

The signctx_init() and signctx() methods are used to sign a digest represented by an EVP_MD_CTX object. They are called by the EVP_DigestSignInit(3) functions.

int (*verifyctx_init)(EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx)
int (*verifyctx)(
EVP_PKEY_CTX *ctx,
const unsigned char *sig,
int siglen,
EVP_MD_CTX *mctx);

The verifyctx_init() and verifyctx() methods are used to verify a signature against the data in an EVP_MD_CTX object. They are called by the EVP_DigestVerifyInit(3) functions.

int (*encrypt_init)(EVP_PKEY_CTX *ctx)
int (*encrypt)(
EVP_PKEY_CTX *ctx,
unsigned char *out,
size_t *outlen,
const unsigned char *in,
size_t inlen);

The encrypt_init() and encrypt() methods are used to encrypt a piece of data. They are called by EVP_PKEY_encrypt_init(3) and EVP_PKEY_encrypt(3).

int (*decrypt_init)(EVP_PKEY_CTX *ctx)
int (*decrypt)(
EVP_PKEY_CTX *ctx,
unsigned char *out,
size_t *outlen,
const unsigned char *in,
size_t inlen);

The decrypt_init() and decrypt() methods are used to decrypt a piece of data. They are called by EVP_PKEY_decrypt_init(3) and EVP_PKEY_decrypt(3).

int (*derive_init)(EVP_PKEY_CTX *ctx)
int (*derive)(
EVP_PKEY_CTX *ctx,
unsigned char *key,
size_t *keylen);

The derive_init() and derive() methods are used to derive the shared secret from a public key algorithm (for instance, the DH algorithm). They are called by EVP_PKEY_derive_init(3) and EVP_PKEY_derive(3).

int (*ctrl)(
EVP_PKEY_CTX *ctx,
int type,
int p1,
void *p2);
int (*ctrl_str)(
EVP_PKEY_CTX *ctx,
const char *type,
const char *value);

The ctrl() and ctrl_str() methods are used to adjust algorithm-specific settings. See EVP_PKEY_CTX_ctrl(3) for details.

int (*check)(EVP_PKEY *pkey)
int (*public_check)(EVP_PKEY *pkey)
int (*param_check)(EVP_PKEY *pkey)

These methods are used to validate a key pair, the public component, and the parameters for the given pkey, respectively. They are called by EVP_PKEY_check(3), EVP_PKEY_public_check(3), and EVP_PKEY_param_check(3), respectively.

Functions

EVP_PKEY_meth_new() creates a new EVP_PKEY_METHOD object with the given id and flags. The following flags are supported:

EVP_PKEY_FLAG_AUTOARGLEN: Automatically calculate the maximum size of the output buffer in corresponding EVP methods by the EVP framework. Thus the implementations of these methods don't need to care about handling the case of returning output buffer size by themselves. For details on the output buffer size, refer to EVP_PKEY_sign(3).
EVP_PKEY_FLAG_SIGCTX_CUSTOM: Indicate that the signctx() method of an EVP_PKEY_METHOD is always called by the EVP framework while doing a digest signing operation by calling EVP_DigestSignFinal(3).

EVP_PKEY_meth_free() frees pmeth.

EVP_PKEY_meth_copy() copies src to dst.

EVP_PKEY_meth_find() finds an EVP_PKEY_METHOD object with the given id. This function first searches through the user-defined method objects and then through the built-in objects.

EVP_PKEY_meth_add0() adds pmeth to the stack of user defined methods.

The EVP_PKEY_meth_set_*() functions set the corresponding fields of pmeth to the arguments passed.

EVP_PKEY_CTX_get_data() retrieves algorithm- and implementation-specific private key data from ctx. Public key algorithm implementations typically allocate and initialize this data automatically in their init() function.

EVP_PKEY_CTX_set_data() transfers ownership of the given data to ctx, replacing the existing algorithm- and implementation-specific private key data. It is the responsibility of the caller to free the existing data before calling this function.

RETURN VALUES

EVP_PKEY_meth_new() returns a pointer to a new EVP_PKEY_METHOD object or NULL on error.

EVP_PKEY_meth_find() returns a pointer to the found EVP_PKEY_METHOD object or NULL if no matching object is found.

EVP_PKEY_meth_add0() returns 1 if the method is added successfully or 0 if an error occurred.

EVP_PKEY_CTX_get_data() returns an internal pointer owned by ctx.

HISTORY

EVP_PKEY_meth_new(), EVP_PKEY_meth_free(), EVP_PKEY_meth_find(), EVP_PKEY_meth_add0(), EVP_PKEY_meth_set_init(), EVP_PKEY_meth_set_copy(), EVP_PKEY_meth_set_cleanup(), EVP_PKEY_meth_set_paramgen(), EVP_PKEY_meth_set_keygen(), EVP_PKEY_meth_set_sign(), EVP_PKEY_meth_set_verify(), EVP_PKEY_meth_set_verify_recover(), EVP_PKEY_meth_set_signctx(), EVP_PKEY_meth_set_verifyctx(), EVP_PKEY_meth_set_encrypt(), EVP_PKEY_meth_set_decrypt(), EVP_PKEY_meth_set_derive(), EVP_PKEY_meth_set_ctrl(), EVP_PKEY_CTX_get_data(), and EVP_PKEY_CTX_set_data() first appeared in OpenSSL 1.0.0 and have been available since OpenBSD 4.9.

EVP_PKEY_meth_copy() first appeared in OpenSSL 1.0.1 and has been available since OpenBSD 5.3.

EVP_PKEY_meth_set_check(), EVP_PKEY_meth_set_public_check(), and EVP_PKEY_meth_set_param_check() first appeared in OpenSSL 1.1.1 and have been available since OpenBSD 7.1.

Sepember 9, 2023

Sortix 1.1.0-dev