3.6 Digital signatures

A digital signature is a relation between a key and data that only someone who knows the key can compute.

Signing uses a private key, and verifying a signature uses the corresponding public key of the signing entity. This library supports RSA, ECDSA and Ed25519 signatures. You can use load_private_key/3 and load_public_key/2 to load keys from files and streams.

In typical cases, we use this mechanism to sign the hash of data. See hashing (section 3.5). For this reason, the following predicates work on the hexadecimal representation of hashes that is also used by crypto_data_hash/3 and related predicates.

Signatures are also represented in hexadecimal notation, and you can use hex_bytes/2 to convert them to and from lists of bytes (integers).

3.6.1 ECDSA

ecdsa_sign(+Key, +Data, -Signature, +Options)

Create an ECDSA signature for Data with EC private key Key. Among the most common cases is signing a hash that was created with crypto_data_hash/3 or other predicates of this library. For this reason, the default encoding (hex) assumes that Data is an atom, string, character list or code list representing the data in hexadecimal notation. See rsa_sign/4 for an example.

Options:

encoding(+Encoding)

Encoding to use for Data. Default is hex. Alternatives are octet, utf8 and text.

[semidet]ecdsa_verify(+Key, +Data, +Signature, +Options)

True iff Signature can be verified as the ECDSA signature for Data, using the EC public key Key.

Options:

encoding(+Encoding)

Encoding to use for Data. Default is hex. Alternatives are octet, utf8 and text.

3.6.2 RSA

[det]rsa_sign(+Key, +Data, -Signature, +Options)

Create an RSA signature for Data with private key Key. Options:

type(+Type)

SHA algorithm used to compute the digest. Values are sha1, sha224, sha256, sha384 or sha512. The default is a cryptographically secure algorithm. If you specify a variable, then it is unified with the algorithm that was used.

encoding(+Encoding)

Encoding to use for Data. Default is hex. Alternatives are octet, utf8 and text.

This predicate can be used to compute a sha256WithRSAEncryption signature as follows:

sha256_with_rsa(PemKeyFile, Password, Data, Signature) :-
    Algorithm = sha256,
    read_key(PemKeyFile, Password, Key),
    crypto_data_hash(Data, Hash, [algorithm(Algorithm),
                                  encoding(octet)]),
    rsa_sign(Key, Hash, Signature, [type(Algorithm)]).

read_key(File, Password, Key) :-
    setup_call_cleanup(
        open(File, read, In, [type(binary)]),
        load_private_key(In, Password, Key),
        close(In)).

Note that a hash that is computed by crypto_data_hash/3 can be directly used in rsa_sign/4 as well as ecdsa_sign/4.

[semidet]rsa_verify(+Key, +Data, +Signature, +Options)

Verify an RSA signature for Data with public key Key.

Options:

type(+Type)

SHA algorithm used to compute the digest. Values are sha1, sha224, sha256, sha384 or sha512. The default is the same as for rsa_sign/4. This option must match the algorithm that was used for signing. When operating with different parties, the used algorithm must be communicated over an authenticated channel.

encoding(+Encoding)

Encoding to use for Data. Default is hex. Alternatives are octet, utf8 and text.

3.6.3 Ed25519

Ed25519 (RFC 8032) is a signature scheme over a twisted Edwards curve that is birationally equivalent to Curve25519. A key pair is derived from 32 arbitrary bytes and is represented in PKCS#8 v2 format (RFC 8410), the format also used by openssl genpkey -algorithm ed25519.

Unlike ECDSA and RSA above, Ed25519 signs the data itself rather than a hash of it. The default encoding of Data is therefore utf8.

[det]ed25519_new_keypair(-KeyPair)

KeyPair is a new Ed25519 key pair, created from 32 random bytes obtained with crypto_n_random_bytes/2. It contains the private key and must be kept absolutely secret. See ed25519_seed_keypair/2.

[det]ed25519_seed_keypair(+Seed, -KeyPair)

Deterministically derive an Ed25519 key pair from Seed, 32 arbitrary bytes. Seed can be chosen at random using crypto_n_random_bytes/2 or derived from input keying material using crypto_data_hkdf/4.

KeyPair is a hexadecimal atom denoting the key pair in PKCS#8 v2 format (RFC 5958, RFC 8410), the format also used by openssl genpkey -algorithm ed25519. It contains the private key and must be kept absolutely secret. It can be used for signing with ed25519_sign/4, and its public key is obtained with ed25519_keypair_public_key/2.

[det]ed25519_keypair_public_key(+KeyPair, -PublicKey)

PublicKey is the public key of KeyPair, a hexadecimal atom. The public key is used for signature verification with ed25519_verify/4 and can be shared freely.

[det]ed25519_sign(+KeyPair, +Data, -Signature, +Options)

Create an Ed25519 (RFC 8032) signature for Data with the private key of KeyPair, as created by ed25519_new_keypair/1 or obtained with load_private_key/3. Signature is a hexadecimal atom.

Options:

encoding(+Encoding)

Encoding to use for Data. Default is utf8. Alternatives are octet, text and hex. Note that this differs from ecdsa_sign/4 and rsa_sign/4, which default to hex because they are typically applied to a hash of the data. Ed25519 signs the data itself.

[semidet]ed25519_verify(+PublicKey, +Data, +Signature, +Options)

True iff Signature can be verified as the Ed25519 signature for Data, using PublicKey.

Options are as for ed25519_sign/4.