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 shared “parameters.” For example, elliptic curve (EC) keys only interoperate if they use the “curve” (comprising a modulus, a polynomial equation, and a generator point). That is, EC keys have one parameter, the curve, in addition to the key-specific public value, a point on that curve. Keys only interoperate if they have the same parameter values. The following key types have parameters: 'dsa, 'dh, 'ec, 'eddsa, and 'ecx. The 'rsa system does not; the bit-length of an RSA public modulus is not a parameter.

Equivalent to (and (pk-key? v) (not (private-key? v))).

Added in version 1.8 of package crypto-lib.

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, and any other party can verify the sender’s signature using the sender’s public key.

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

With 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 should be a digest computed with dspec (in particular, the length of msg must be the output size of 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 or Diffie-Hellman) 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 key-derivation function (see kdf).

5.5 PK External Representations🔗ℹ

This section describes serialization of public and private keys in various formats. See also PKCS #8 Encrypted Private Keys.

• '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 [PKIX-AlgId, PKIX-EdC].

• 'PrivateKeyInfo — DER-encoded PrivateKeyInfo [PKCS8] or OneAsymmetricKey [AKP] 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.

  OneAsymmetricKey is essentially PrivateKeyInfo v2; it adds an optional field for the public key. The OneAsymmetricKey (v2) format is automatically used when necessary; otherwise, the PrivateKeyInfo (v1) format is used when the private key format already includes the public components.

• 'OneAsymmetricKey — Alias for 'PrivateKeyInfo.

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

• 'age/v1-private — String encoded in the age-encryption (v1) format, representing an X25519 private key. The string is Bech32-encoded and has 74 characters beginning with AGE-SECRET-KEY-1.

• 'age/v1-public — String encoded in the age-encryption (v1) format, representing an X25519 public key. The string is Bech32-encoded and has 62 characters beginning with age1.

• 'openssh-public — A string containing an OpenSSH-format public key. The string starts with a tag such as ssh-rsa or ssh-ed25519, then contains the key data encoded in Base64. Only RSA, Ed25519, and Ed448 public keys are currently supported.

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

  • (list 'rsa 'private 0 n e d p q dp dq qInv)

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

  • (list 'dh 'private p g q j seed pgen y x)

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

  • (list 'ec 'private curve-oid q-bytes d)

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

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

• '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 'private p g q j seed pgen y)

  • (list 'dh 'public p g y)

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

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

  • (list 'ecx 'public curve-sym q-bytes)

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 formats.
Changed in version 1.9: Added 'age/v1-public, 'age/v1-private, and 'openssh-public formats.
Changed in version 2.0: Added the longer DH variants of 'rkt-public and 'rkt-private encodings.
Changed in version 2.0: Previously, SubjectPublicKeyInfo encoding of DH keys used the PKCS #3 identifier and parameters [PKCS3] for compatibility with old versions of OpenSSL.

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

Changed in version 2.0 of package crypto-lib: Generalized sources argument from factories to allow PK implementations also.

• '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.

• 'DSAParameters — DER-encoded Dss-Parms [PKIX-AlgId] for DSA parameters.

• 'DomainParameters — DER-encoded DomainParameters [PKIX-AlgId] for DH parameters.

• 'DHParameter — DER-encoded DHParameter [PKCS3] for DH parameters. (This format contains insufficient information for parameter validation.)

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

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

  • (list 'dsa 'params p q g)

  • (list 'dh 'params p g q j seed pgen)

  • (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.
Changed in version 2.0: Added the longer DH variants of the 'rkt-params encoding.
Changed in version 2.0: Previously, AlgorithmIdentifier encoding of DH keys used the PKCS #3 identifier and parameters [PKCS3] for compatibility with old versions of OpenSSL.

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🔗ℹ