Sortix cross-nightly manual

This manual documents Sortix cross-nightly. You can instead view this document in the latest official manual.

NAME

RSA_meth_new, RSA_meth_dup, RSA_meth_free, RSA_meth_get0_name, RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags, RSA_meth_get0_app_data, RSA_meth_set0_app_data, RSA_meth_get_init, RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish, RSA_meth_get_pub_enc, RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec, RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec, RSA_meth_set_priv_dec, RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify, RSA_meth_set_verify, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp, RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_keygen, RSA_meth_set_keygen — build up RSA methods

SYNOPSIS

#include <openssl/rsa.h>

RSA_METHOD *
RSA_meth_new(const char *name, int flags);

RSA_METHOD *
RSA_meth_dup(const RSA_METHOD *meth);

void
RSA_meth_free(RSA_METHOD *meth);

const char *
RSA_meth_get0_name(const RSA_METHOD *meth);

int
RSA_meth_set1_name(RSA_METHOD *meth, const char *name);

int
RSA_meth_get_flags(const RSA_METHOD *meth);

int
RSA_meth_set_flags(RSA_METHOD *meth, int flags);

void *
RSA_meth_get0_app_data(const RSA_METHOD *meth);

int
RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data);

int
(*RSA_meth_get_init(const RSA_METHOD *meth))(RSA *rsa);

int
RSA_meth_set_init(RSA_METHOD *meth, int (*init)(RSA *rsa));

int
(*RSA_meth_get_finish(const RSA_METHOD *meth))(RSA *rsa);

int
RSA_meth_set_finish(RSA_METHOD *meth, int (*finish)(RSA *rsa));

int
(*RSA_meth_get_pub_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding);

int
RSA_meth_set_pub_enc(RSA_METHOD *meth, int (*pub_enc)(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding));

int
(*RSA_meth_get_pub_dec(const RSA_METHOD *meth))(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding);

int
RSA_meth_set_pub_dec(RSA_METHOD *meth, int (*pub_dec)(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding));

int
(*RSA_meth_get_priv_enc(const RSA_METHOD *meth))(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding);

int
RSA_meth_set_priv_enc(RSA_METHOD *meth, int (*priv_enc)(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding));

int
(*RSA_meth_get_priv_dec(const RSA_METHOD *meth))(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding);

int
RSA_meth_set_priv_dec(RSA_METHOD *meth, int (*priv_dec)(int flen, const unsigned char *from, unsigned char *to, RSA *rsa, int padding));

int
(*RSA_meth_get_sign(const RSA_METHOD *meth))(int type, const unsigned char *m, unsigned int m_length, unsigned char *sigret, unsigned int *siglen, const RSA *rsa);

int
RSA_meth_set_sign(RSA_METHOD *rsa, int (*sign)(int type, const unsigned char *m, unsigned int m_length, unsigned char *sigret, unsigned int *siglen, const RSA *rsa));

int
(*RSA_meth_get_verify(const RSA_METHOD *meth))(int dtype, const unsigned char *m, unsigned int m_length, const unsigned char *sigbuf, unsigned int siglen, const RSA *rsa);

int
RSA_meth_set_verify(RSA_METHOD *rsa, int (*verify)(int dtype, const unsigned char *m, unsigned int m_length, const unsigned char *sigbuf, unsigned int siglen, const RSA *rsa));

int
(*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx);

int
RSA_meth_set_mod_exp(RSA_METHOD *meth, int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa, BN_CTX *ctx));

int
(*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth))(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);

int
RSA_meth_set_bn_mod_exp(RSA_METHOD *meth, int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx));

int
(*RSA_meth_get_keygen(const RSA_METHOD *meth))(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);

int
RSA_meth_set_keygen(RSA_METHOD *meth, int (*keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb));

DESCRIPTION

The RSA_METHOD structure holds function pointers for custom RSA implementations.

RSA_meth_new() creates a new RSA_METHOD structure. A copy of the NUL-terminated name is stored in the new RSA_METHOD object. Any new RSA object constructed from this RSA_METHOD will have the given flags set by default, as if they were set with RSA_set_flags(3).

RSA_meth_dup() creates a deep copy of meth, except that a pointer stored into it with RSA_meth_set0_app_data() is copied as a pointer without creating a copy of its content. This might be useful for creating a new RSA_METHOD based on an existing one, but with some differences.

RSA_meth_free() destroys meth and frees any memory associated with it, except that memory pointed to by a pointer set with RSA_meth_set0_app_data() is not freed. If meth is NULL, no action occurs.

RSA_meth_get0_name() returns an internal pointer to the name of meth. RSA_meth_set1_name() stores a copy of the NUL-terminated name in the RSA_METHOD object after freeing the previously stored name. Method names are ignored by the default RSA implementation but can be used by alternative implementations and by the application program.

RSA_meth_get_flags() retrieves the flags from meth. Flags are documented in RSA_test_flags(3). RSA_meth_set_flags() overwrites all flags in meth. Unlike RSA_set_flags(3), it does not preserve any flags that were set before the call.

RSA_meth_get0_app_data() and RSA_meth_set0_app_data() get and set a pointer to implementation-specific data. The function RSA_meth_free() does not free(3) the memory pointed to by app_data. The default RSA implementation does not use app_data.

RSA_meth_get_init() and RSA_meth_set_init() get and set an optional function used when creating a new RSA object. Unless init is NULL, it will be called at the end of RSA_new(3), RSA_new_method(3), and RSA_set_method(3), passing a pointer to the newly allocated or reset RSA object as an argument. The default RSA implementation, RSA_PKCS1_SSLeay(3), contains an init function equivalent to calling RSA_set_flags(3) with an argument of RSA_FLAG_CACHE_PUBLIC | RSA_FLAG_CACHE_PRIVATE.

RSA_meth_get_finish() and RSA_meth_set_finish() get and set an optional function for destroying an RSA object. Unless finish is NULL, it will be called from RSA_set_method(3) and from RSA_free(3). It takes the same argument as RSA_free(3) and is intended to do RSA implementation specific cleanup. The memory used by the RSA object itself should not be freed by the finish function. The default RSA implementation contains a finish function freeing the memory used by the RSA_FLAG_CACHE_PUBLIC and RSA_FLAG_CACHE_PRIVATE caches.

RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(), RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(), RSA_meth_get_priv_enc(), RSA_meth_set_priv_enc(), RSA_meth_get_priv_dec(), and RSA_meth_set_priv_dec() get and set the mandatory functions used for public and private key encryption and decryption. These functions will be called from RSA_public_encrypt(3), RSA_public_decrypt(3), RSA_private_encrypt(3), and RSA_private_decrypt(3), respectively, and take the same parameters as those.

RSA_meth_get_sign(), RSA_meth_set_sign(), RSA_meth_get_verify(), and RSA_meth_set_verify() get and set the optional functions used for creating and verifying an RSA signature. If the flag RSA_FLAG_SIGN_VER is set on the RSA object in question and sign or verify is not NULL, it will be called from RSA_sign(3) or RSA_verify(3), respectively, and take the same parameters as those. Otherwise, RSA_private_encrypt(3) or RSA_public_decrypt(3) will be used instead.

RSA_meth_get_mod_exp() and RSA_meth_set_mod_exp() get and set the function used for Chinese Remainder Theorem (CRT) computations involving the p, q, dmp1, dmq1, and iqmp fields of an RSA object. It is used by the default RSA implementation during RSA_private_encrypt(3) and RSA_private_decrypt(3) when the required components of the private key are available or when the RSA_FLAG_EXT_PKEY flag is set.

RSA_meth_get_bn_mod_exp() and RSA_meth_set_bn_mod_exp() get and set the function used for CRT computations, specifically the value r = a ^ p mod m. It is used by the default RSA implementation during RSA_public_encrypt(3) and RSA_public_decrypt(3) and as a fallback during RSA_private_encrypt(3) and RSA_private_decrypt(3).

RSA_meth_get_keygen() and RSA_meth_set_keygen() get and set the optional function used for generating a new RSA key pair. Unless keygen is NULL, it will be called from RSA_generate_key_ex(3) and takes the same parameters. Otherwise, a builtin default implementation is used.

RETURN VALUES

RSA_meth_new() and RSA_meth_dup() return the newly allocated RSA_METHOD object or NULL on failure.

RSA_meth_get0_name() returns an internal pointer which must not be freed by the caller.

RSA_meth_get_flags() returns zero or more RSA_FLAG_* constants OR'ed together, or 0 if no flags are set in meth.

RSA_meth_get0_app_data() returns the pointer that was earlier passed to RSA_meth_set0_app_data() or NULL otherwise.

All other RSA_meth_get_*() functions return the appropriate function pointer that has been set with the corresponding RSA_meth_set_*() function, or NULL if no such pointer has been set in meth.

All RSA_meth_set*() functions return 1 on success or 0 on failure. In the current implementation, only RSA_meth_set1_name() can actually fail.

HISTORY

These functions first appeared in OpenSSL 1.1.0. RSA_meth_new(), RSA_meth_dup(), RSA_meth_free(), RSA_meth_set_finish(), RSA_meth_set_priv_enc(), and RSA_meth_set_priv_dec() have been available since OpenBSD 6.3, RSA_meth_set1_name() and RSA_meth_get_finish() since OpenBSD 6.4, and RSA_meth_get0_name(), RSA_meth_get_flags(), RSA_meth_set_flags(), RSA_meth_get0_app_data(), RSA_meth_set0_app_data(), RSA_meth_get_init(), RSA_meth_set_init(), RSA_meth_set_finish(), RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(), RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(), RSA_meth_get_priv_enc(), RSA_meth_get_priv_dec(), RSA_meth_get_sign(), RSA_meth_set_sign(), RSA_meth_get_verify(), RSA_meth_set_verify(), RSA_meth_get_mod_exp(), RSA_meth_set_mod_exp(), RSA_meth_get_bn_mod_exp(), RSA_meth_set_bn_mod_exp(), RSA_meth_get_keygen(), and RSA_meth_set_keygen() since OpenBSD 6.6.