pub struct KeyPair { /* private fields */ }
Expand description
An RSA key pair, used for signing.
Implementations§
source§impl KeyPair
impl KeyPair
sourcepub fn from_pkcs8(pkcs8: &[u8]) > Result<Self, KeyRejected>
pub fn from_pkcs8(pkcs8: &[u8]) > Result<Self, KeyRejected>
Parses an unencrypted PKCS#8encoded RSA private key.
This will generate a 2048bit RSA private key of the correct form using OpenSSL’s command line tool:
openssl genpkey algorithm RSA \
pkeyopt rsa_keygen_bits:2048 \
pkeyopt rsa_keygen_pubexp:65537  \
openssl pkcs8 topk8 nocrypt outform der > rsa2048privatekey.pk8
This will generate a 3072bit RSA private key of the correct form:
openssl genpkey algorithm RSA \
pkeyopt rsa_keygen_bits:3072 \
pkeyopt rsa_keygen_pubexp:65537  \
openssl pkcs8 topk8 nocrypt outform der > rsa3072privatekey.pk8
Often, keys generated for use in OpenSSLbased software are stored in the Base64 “PEM” format without the PKCS#8 wrapper. Such keys can be converted to binary PKCS#8 form using the OpenSSL command line tool like this:
openssl pkcs8 topk8 nocrypt outform der \
in rsa2048privatekey.pem > rsa2048privatekey.pk8
Base64 (“PEM”) PKCS#8encoded keys can be converted to the binary PKCS#8 form like this:
openssl pkcs8 nocrypt outform der \
in rsa2048privatekey.pem > rsa2048privatekey.pk8
See Self::from_components
for more details on how the input is
validated.
See RFC 5958 and RFC 3447 Appendix A.1.2 for more details of the encoding of the key.
sourcepub fn from_der(input: &[u8]) > Result<Self, KeyRejected>
pub fn from_der(input: &[u8]) > Result<Self, KeyRejected>
Parses an RSA private key that is not inside a PKCS#8 wrapper.
The private key must be encoded as a binary DERencoded ASN.1
RSAPrivateKey
as described in RFC 3447 Appendix A.1.2). In all other
respects, this is just like from_pkcs8()
. See the documentation for
from_pkcs8()
for more details.
It is recommended to use from_pkcs8()
(with a PKCS#8encoded key)
instead.
See Self::from_components()
for more details on how the input is
validated.
sourcepub fn from_components<Public, Private>(
components: &KeyPairComponents<Public, Private>,
) > Result<Self, KeyRejected>
pub fn from_components<Public, Private>( components: &KeyPairComponents<Public, Private>, ) > Result<Self, KeyRejected>
Constructs an RSA private key from its bigendianencoded components.
Only twoprime (not multiprime) keys are supported. The public modulus (n) must be at least 2047 bits. The public modulus must be no larger than 4096 bits. It is recommended that the public modulus be exactly 2048 or 3072 bits. The public exponent must be at least 65537 and must be no more than 33 bits long.
The private key is validated according to [NIST SP80056B rev. 1] section 6.4.1.4.3, crt_pkv (Intended ExponentCreation Method Unknown), with the following exceptions:

Section 6.4.1.2.1, Step 1: Neither a target security level nor an expected modulus length is provided as a parameter, so checks regarding these expectations are not done.

Section 6.4.1.2.1, Step 3: Since neither the public key nor the expected modulus length is provided as a parameter, the consistency check between these values and the private key’s value of n isn’t done.

Section 6.4.1.2.1, Step 5: No primality tests are done, both for performance reasons and to avoid any side channels that such tests would provide.

Section 6.4.1.2.1, Step 6, and 6.4.1.4.3, Step 7:
 ring has a slightly looser lower bound for the values of
p
andq
than what the NIST document specifies. This looser lower bound matches what most other crypto libraries do. The check might be tightened to meet NIST’s requirements in the future. Similarly, the check thatp
andq
are not too close together is skipped currently, but may be added in the future.
 The validity of the mathematical relationship of
dP
,dQ
,e
andn
is verified only during signing. Some size checks ofd
,dP
anddQ
are performed at construction, but some NIST checks are skipped because they would be expensive and/or they would leak information through side channels. If a preemptive check of the consistency ofdP
,dQ
,e
andn
with each other is necessary, that can be done by signing any message with the key pair.
d
is not fully validated, neither at construction nor during signing. This is OK as far as ring’s usage of the key is concerned because ring never uses the value ofd
(ring always usesp
,q
,dP
anddQ
via the Chinese Remainder Theorem, instead). However, ring’s checks would not be sufficient for validating a key pair for use by some other system; that other system must check the value ofd
itself ifd
is to be used.
 ring has a slightly looser lower bound for the values of
sourcepub fn public_modulus_len(&self) > usize
👎Deprecated: Use public().modulus_len()
pub fn public_modulus_len(&self) > usize
public().modulus_len()
Returns the length in bytes of the key pair’s public modulus.
A signature has the same length as the public modulus.
source§impl KeyPair
impl KeyPair
sourcepub fn sign(
&self,
padding_alg: &'static dyn RsaEncoding,
rng: &dyn SecureRandom,
msg: &[u8],
signature: &mut [u8],
) > Result<(), Unspecified>
pub fn sign( &self, padding_alg: &'static dyn RsaEncoding, rng: &dyn SecureRandom, msg: &[u8], signature: &mut [u8], ) > Result<(), Unspecified>
Computes the signature of msg
and writes it into signature
.
msg
is digested using the digest algorithm from padding_alg
and the
digest is then padded using the padding algorithm from padding_alg
.
The signature it written into signature
; signature
’s length must be
exactly the length returned by self::public().modulus_len()
or else
an error will be returned. On failure, signature
may contain
intermediate results, but won’t contain anything that would endanger the
private key.
rng
may be used to randomize the padding (e.g. for PSS).
Many other crypto libraries have signing functions that takes a
precomputed digest as input, instead of the message to digest. This
function does not take a precomputed digest; instead, sign
calculates the digest itself.