RSA_NEW(3) | Library Functions Manual | RSA_NEW(3) |

`RSA_new`

, `RSA_up_ref`

,
`RSA_free`

—
allocate and free RSA objects

`#include <openssl/rsa.h>`

`RSA *`

`RSA_new`

(`void`);

`int`

`RSA_up_ref`

(`RSA *rsa`);

`void`

`RSA_free`

(`RSA *rsa`);

`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.

`RSA_up_ref`

() increments the reference
count by 1.

`RSA_free`

() decrements the reference count
by 1. If it reaches 0, it 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.

`RSA_new`

() returns
`NULL`

and sets an error code that can be obtained by
ERR_get_error(3). Otherwise it
returns a pointer to the newly allocated structure.
`RSA_up_ref`

() returns 1 for success or 0
for failure.

RSA was covered by a US patent which expired in September 2000.

`RSA_new`

() and `RSA_free`

()
appeared in SSLeay 0.4 or earlier and 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.

April 18, 2018 | OpenBSD-current |