3.3 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.2). 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:

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.

[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 (default), sha224, sha256, sha384 or sha512.

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 (default), sha224, sha256, sha384 or sha512.

encoding(+Encoding)

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

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