NAME
RSA_new,
RSAPrivateKey_dup,
RSAPublicKey_dup,
RSA_up_ref, RSA_free
— allocate and free RSA
objects
SYNOPSIS
#include
<openssl/rsa.h>
RSA *
RSA_new(void);
RSA *
RSAPrivateKey_dup(RSA *rsa);
RSA *
RSAPublicKey_dup(RSA *rsa);
int
RSA_up_ref(RSA *rsa);
void
RSA_free(RSA *rsa);
DESCRIPTION
The RSA functions implement RSA public key encryption and signatures as defined in PKCS #1 v2.0 (RFC 2437).
RSA_new()
allocates and initializes an RSA structure, setting
the reference count to 1. It is equivalent to calling
RSA_new_method(3) with a NULL
argument.
RSAPrivateKey_dup()
calls RSA_new() and copies the public and private
key components from rsa into the new structure.
RSAPublicKey_dup()
does the same except that it copies the public key components only.
RSA_up_ref()
increments the reference count by 1.
RSA_free()
decrements the reference count by 1. If it reaches 0, it calls the optional
finish function set up with
RSA_meth_set_finish(3), calls
ENGINE_finish(3) if rsa uses an engine,
and frees the RSA structure and its components. The
key is erased before the memory is returned to the system. If
rsa is a NULL pointer, no
action occurs.
The RSA structure consists of several BIGNUM components. It can contain public as well as private RSA keys:
typedef struct {
BIGNUM *n; // public modulus
BIGNUM *e; // public exponent
BIGNUM *d; // private exponent
BIGNUM *p; // secret prime factor
BIGNUM *q; // secret prime factor
BIGNUM *dmp1; // d mod (p-1)
BIGNUM *dmq1; // d mod (q-1)
BIGNUM *iqmp; // q^-1 mod p
// ...
} RSA;
In public keys, the private exponent d and
the related secret values p, q,
dmp1, dmp2, and
iqmp are NULL.
p, q,
dmp1, dmq1, and
iqmp may be NULL in private
keys, but the RSA operations are much faster when these values are
available.
Note that RSA keys may use non-standard RSA_METHOD implementations, either directly or by the use of ENGINE modules. In some cases (e.g. an ENGINE providing support for hardware-embedded keys), these BIGNUM values will not be used by the implementation or may be used for alternative data storage. For this reason, applications should generally avoid using RSA structure elements directly and instead use API functions to query or modify keys.
RETURN VALUES
RSA_new(),
RSAPrivateKey_dup(), and
RSAPublicKey_dup() return a pointer to the newly
allocated structure, or NULL if an error occurs. An
error code can be obtained by
ERR_get_error(3).
RSA_up_ref() returns 1 for success or 0
for failure.
SEE ALSO
BN_new(3), crypto(3), d2i_RSAPublicKey(3), DH_new(3), DSA_new(3), EVP_PKEY_set1_RSA(3), RSA_blinding_on(3), RSA_check_key(3), RSA_generate_key(3), RSA_get0_key(3), RSA_get_ex_new_index(3), RSA_meth_new(3), RSA_padding_add_PKCS1_type_1(3), RSA_pkey_ctx_ctrl(3), RSA_print(3), RSA_private_encrypt(3), RSA_PSS_PARAMS_new(3), RSA_public_encrypt(3), RSA_security_bits(3), RSA_set_method(3), RSA_sign(3), RSA_sign_ASN1_OCTET_STRING(3), RSA_size(3)
STANDARDS
SSL, PKCS #1 v2.0
RSA was covered by a US patent which expired in September 2000.
HISTORY
RSA_new() and
RSA_free() appeared in SSLeay 0.4 or earlier.
RSAPrivateKey_dup() first appeared in SSLeay 0.5.1
and RSAPublicKey_dup() in SSLeay 0.5.2. These
functions have been available since OpenBSD 2.4.
RSA_up_ref() first appeared in OpenSSL
0.9.7 and has been available since OpenBSD 3.2.