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 both RSA and ECDSA 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.