5 Public-Key Cryptography

Public-key (PK) cryptography covers operations such as signing, encryption, and key agreement between parties that do not start with any shared secrets. Instead of shared secrets, each party possesses a keypair consisting of a secret private key and a widely-published public key. Not all PK cryptosystems support all PK operations (for example, DSA does not support encryption or secret derivation), and some PK implementations may support a subset of a PK cryptosystem’s potential operations.

A PK cryptosystem specifies the information represented by the public and private keys and the algorithms that operate on that information. The following PK systems are supported:

• 'rsa — RSA keys with RSAES-* encryption and RSASSA-* signing.

• 'dsa — DSA keys with DSA signing.

• 'dh — Diffie-Hellman keys with DH key agreement.

• 'ec — Elliptic curve keys with ECDSA signing and ECDH key agreement. Only named curves are supported, and different implementations support different curves; use factory-print-info to see supported curves.

• 'eddsa — Edwards curve keys with EdDSA signing, specifically Ed25519 and Ed448.

• 'ecx — Montgomery curve keys with ECDH key agreement, specifically X25519 and X448.

Changed in version 1.1 of package crypto-lib: Added 'eddsa and 'ecx.

Note that the functions only report the capabilities of the cryptosystem implementation, regardless of the limitations of pk if pk is a key. For example, (pk-can-sign? pk) would return true when pk is an RSA public-only key, even though signing requires a private key.

5.1 PK Keys and Parameters

A PK keypair consists of public key component and private key components. A public key is a key that contains the public key components. In this library, a private key contains both private and public components, so it can also be used wherever a public key is required. That is, every private key is also a public key. This library uses the term “public-only key” to refer to a public key that is not a private key.

In some PK cryptosystems, the public components are further divided into key-specific values and “key parameters.” Key parameters are public quantities that are expensive to compute; they can be generated once and many keypairs can use the same parameter values. For example, a DSA key requires a large prime with certain relatively rare mathematical properties, and so finding such a prime is relatively expensive, but once a suitable prime is found, generating private keys is relatively fast, and since the prime is public, many keypairs can use the same prime. Elliptic curve (EC) cryptography is another example: the key parameter is the curve equation, and the public and private key components are points on the curve. In contrast, RSA does not have key parameters; simple quantities like the size of an RSA modulus are not key parameters.

Changed in version 1.1 of package crypto-lib: Added 'eddsa and 'ecx options.

5.2 PK Signatures

In PK signing, the sender uses their own private key to sign a message; any other party can verify the sender’s signature using the sender’s public key.

In RSA, DSA, and ECDSA, only short messages can be signed directly (limits are generally proportional to the size of the keys), so a typical process is to compute a digest of the message and sign the digest. The message and digest signature are sent together, possibly with additional data.

In EdDSA, messages are signed directly. (The signing process computes a message digest internally.)

If pk is an RSA private key, then dspec must be the name of a digest algorithm, and msg must be a digest computed with dspec (in particular, it must have the correct size for dspec). The resulting signature depends on the identity of the digest algorithm. Different RSA implementations may support different digest algorithms.

If pk is a DSA or EC private key, the signature does not depend on the digest algorithm; the dspec should be omitted. (For backwards compatibility, the dspec argument is accepted, but it has no effect other than checking the length of msg.)

If pk is a EdDSA private key, then dspec must be #f or 'none (both values mean the same thing). The message may be of any length, and the EdDSA signature is computed. Future versions of this library may accept other values of dspec and compute HashEdDSA signatures (eg, Ed25519ph) in reponse.

Added in version 1.1 of package crypto-lib.

The dspec and padding arguments have the same meanings as for pk-sign.

Added in version 1.1 of package crypto-lib.

Do not use these functions with EdDSA keys; use pk-sign and pk-verify directly on the messages. (This library currently does not support pre-hashing EdDSA variants, eg Ed25519ph.)

5.3 PK Encryption

In PK encryption, the sender uses the public key of the intended receiver to encrypt a message; the receiver decrypts the message with the receiver’s own private key. Only short messages can be directly encrypted using PK cryptosystems (limits are generally proportional to the size of the PK keys), so a typical approach is to encrypt the message using a symmetric cipher with a randomly-generated key (sometimes called the bulk encryption key) and encrypt that key using PK cryptography. The symmetric-key-encrypted message and PK-encrypted symmetric key are sent together, perhaps with additional data such as a MAC. PK encryption is supported by the RSA cryptosystem.

If pk is an RSA key, then padding choses between PKCS#1-v1.5 padding and OAEP padding [PKCS1]. If padding is #f, then an implementation-dependent mode is chosen. For all other cryptosystems, padding must be #f.

If msg is too large to encrypt using pk, then an exception is raised.

5.4 PK Key Agreement

In PK key agreement (sometimes called key exchange) two parties derive a shared secret by exchanging public keys. Each party can compute the secret from their own private key and the other’s public key, but it is believed infeasible for an observer to compute the secret from the two public keys alone. PK secret derivation is supported by the 'dh, 'ec, and 'ecx cryptosystems.

Note that the derived secret is a deterministic function of the private keys: if two parties perform secret derivation twice, they will produce the same secret both times. In addition, the secret is not uniformly distributed. For these reasons, the derived secret should not be used directly as a key; instead, it should be used to generate key material using a process such as described in RFC 2631 [RFC2631].

5.5 PK External Representations

This section describes serialization of public and private keys in various formats.

• 'SubjectPublicKeyInfo — DER-encoded SubjectPublicKeyInfo [PKIX] representation of the public part of pk. All key types are supported, and an identifier for the key type is embedded in the encoding.

  For compatibility with OpenSSL, DH keys are encoded using the PKCS #3 identifier and parameters [PKCS3] rather than those specified by [PKIX-AlgId], and EdDSA keys are encoded using the algorithm identifiers specified in the draft [PKIX-EdC].

• 'PrivateKeyInfo — DER-encoded PrivateKeyInfo [PKCS8] representation of pk, which must be a private key. All key types are supported, and an identifier for the key type is embedded in the encoding.

  For DSA, DH, and EdDSA keys, the PrivateKeyInfo (version 1) format does not store derived public-key fields. Some implementations (eg GCrypt) do not expose the ability to recompute the public key, so they may not be able to read such keys. See also 'OneAsymmetricKey.

• 'OneAsymmetricKey — DER-encoded OneAsymmetricKey [AKP] representation of pk, which must be a private key. OneAsymmetricKey is essentially PrivateKeyInfo version 2; it adds an optional field for the public key. Prefer OneAsymmetricKey for storing DSA, DH, and EdDSA keys.

• 'RSAPrivateKey — DER-encoded RSAPrivateKey [PKCS1] representation of pk, which must be an RSA private key.

• 'rkt-private — An S-expression of one of the following forms:

  • (list 'rsa 'private n e d)

  • (list 'dsa 'private p q g y d)

  • (list 'dh 'private p g y x)

  • (list 'ec 'private curve-oid q x)

  • (list 'eddsa 'private curve-sym q d)

  • (list 'ecx 'private curve-sym q d)

• 'rkt-public — An S-expression of one of the following forms:

  • (list 'rsa 'public n e)

  • (list 'dsa 'public p q g y)

  • (list 'dh 'public p g y)

  • (list 'ec 'public curve-oid q)

  • (list 'eddsa 'public curve-sym q)

  • (list 'ecx 'private curve-sym q)

More formats may be added in future versions of this library.

Changed in version 1.1 of package crypto-lib: Added 'OneAsymmetricKey, 'rkt-private, and 'rkt-public support.

See pk-key->datum for information about the fmt argument.

• 'AlgorithmIdentifier — DER-encoded AlgorithmIdentifier [PKIX] representation of pkp. All key parameter types are supported, and an identifier for the key parameter type is embedded in the encoding.

  For compatibility with OpenSSL, the PKCS #3 identifier and parameter format [PKCS3] are used rather than those specified by [PKIX-AlgId].

• 'DSAParameters — DER-encoded Dss-Parms [PKIX-AlgId]

• 'DHParameter — DER-encoded DHParameter [PKCS3]. Note: this format differs from the DomainParameters format specified by PKIX.

• 'EcpkParameters — DER-encoded EcpkParameters [PKIX-AlgId] (called ECDomainParameters in [SEC1]).

• 'rkt-params — An S-expression of one of the following forms:

  • (list 'dsa 'params p q g)

  • (list 'dh 'params p g)

  • (list 'ec 'params curve-oid)

  • (list 'eddsa 'params curve-sym)

  • (list 'ecx 'params curve-sym)

More formats may be added in future versions of this library.

Changed in version 1.1 of package crypto-lib: Added 'rkt-params support.

5.6 PKCS #8 Encrypted Private Keys

See pbkdf2-hmac for the meaning of the iterations argument, and see scrypt for the meanings of the N, r, and p arguments.

The following values of cipher-spec are currently supported: '(aes cbc), '(des-ede3 cbc), '(aes gcm), and '(chacha20-poly1305 stream).

The following values of digest-spec are currently supported: 'sha1, 'sha224, 'sha256, 'sha384, and 'sha512.

Compatibility with OpenSSL 1.1.0 has been tested with '(aes cbc) and '(des-ede3 cbc).

If the wrong password is given, then an exception will probably be raised, but for non-AEAD ciphers (such as AES-CBC), there is a possibility that the decryption will succeed and return nonsense.

Bibliography