crypto.pl -- Cryptography and authentication librarycrypto.pl -- Cryptography and authentication libraryThis library provides bindings to functionality of OpenSSL that is related to cryptography and authentication, not necessarily involving connections, sockets or streams.
The hash functionality of this library subsumes and extends that of
library(sha), library(hash_stream) and library(md5) by providing a
unified interface to all available digest algorithms.
The underlying OpenSSL library (libcrypto) is dynamically loaded if
either library(crypto) or library(ssl) are loaded. Therefore, if
your application uses library(ssl), you can use library(crypto) for
hashing without increasing the memory footprint of your application. In
other cases, the specialised hashing libraries are more lightweight but
less general alternatives to library(crypto).
crypto_n_random_bytes(+N, -Bytes) is detOne way to relate such a list of bytes to an integer is to use CLP(FD) constraints as follows:
:- use_module(library(clpfd)).
bytes_integer(Bs, N) :-
foldl(pow, Bs, 0-0, N-_).
pow(B, N0-I0, N-I) :-
B in 0..255,
N #= N0 + B*256^I0,
I #= I0 + 1.
With this definition, you can generate a random 256-bit integer from a list of 32 random bytes:
?- crypto_n_random_bytes(32, Bs), bytes_integer(Bs, I). Bs = [98, 9, 35, 100, 126, 174, 48, 176, 246|...], I = 109798276762338328820827...(53 digits omitted).
The above relation also works in the other direction, letting you translate an integer to a list of bytes. In addition, you can use hex_bytes/2 to convert bytes to tokens that can be easily exchanged in your applications. This also works if you have compiled SWI-Prolog without support for large integers.
crypto_data_hash(+Data, -Hash, +Options) is detmd5 (insecure), sha1 (insecure), ripemd160,
sha224, sha256, sha384, sha512, sha3_224, sha3_256,
sha3_384, sha3_512, blake2s256 or blake2b512. The BLAKE
digest algorithms require OpenSSL 1.1.0 or greater, and the SHA-3
algorithms require OpenSSL 1.1.1 or greater. The default is a
cryptographically secure algorithm. If you specify a variable,
then that variable is unified with the algorithm that was used.utf8. The
other meaningful value is octet, claiming that Data contains
raw bytes. crypto_file_hash(+File, -Hash, +Options) is det crypto_context_new(-Context, +Options) is det crypto_data_context(+Data, +Context0, -Context) is detThis predicate allows a hash to be computed in chunks, which may be important while working with Metalink (RFC 5854), BitTorrent or similar technologies, or simply with big files.
crypto_context_hash(+Context, -Hash) crypto_open_hash_stream(+OrgStream, -HashStream, +Options) is dettrue (default), closing the filter stream also closes the
original (parent) stream. crypto_stream_hash(+HashStream, -Hash) is det crypto_password_hash(+Password, ?Hash) is semidetcrypto_password_hash(Password, Hash, []) and computes a
password-based hash using the default options. crypto_password_hash(+Password, -Hash, +Options) is detAnother important distinction is that equal passwords must yield, with very high probability, different hashes. For this reason, cryptographically strong random numbers are automatically added to the password before a hash is derived.
Hash is unified with an atom that contains the computed hash and all parameters that were used, except for the password. Instead of storing passwords, store these hashes. Later, you can verify the validity of a password with crypto_password_hash/2, comparing the then entered password to the stored hash. If you need to export this atom, you should treat it as opaque ASCII data with up to 255 bytes of length. The maximal length may increase in the future.
Admissible options are:
pbkdf2-sha512 (the default) and bcrypt.Currently, PBKDF2 with SHA-512 is used as the hash derivation function, using 128 bits of salt. All default parameters, including the algorithm, are subject to change, and other algorithms will also become available in the future. Since computed hashes store all parameters that were used during their derivation, such changes will not affect the operation of existing deployments. Note though that new hashes will then be computed with the new default parameters.
crypto_data_hkdf(+Data, +Length, -Bytes, +Options) is detAdmissible options are:
utf8 (default) or octet, denoting
the representation of Data as in crypto_data_hash/3.
The info/1 option can be used to generate multiple keys from a
single master key, using for example values such as key and
iv, or the name of a file that is to be encrypted.
This predicate requires OpenSSL 1.1.0 or greater.
ecdsa_sign(+Key, +Data, -Signature, +Options)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:
hex. Alternatives
are octet, utf8 and text. ecdsa_verify(+Key, +Data, +Signature, +Options) is semidetOptions:
hex. Alternatives
are octet, utf8 and text. hex_bytes(?Hex, ?List) is detExample:
?- hex_bytes('501ACE', Bs).
Bs = [80, 26, 206].
rsa_private_decrypt(+PrivateKey, +CipherText, -PlainText, +Options) is det rsa_private_encrypt(+PrivateKey, +PlainText, -CipherText, +Options) is det rsa_public_decrypt(+PublicKey, +CipherText, -PlainText, +Options) is det rsa_public_encrypt(+PublicKey, +PlainText, -CipherText, +Options) is detOptions:
utf8. Alternatives
are utf8 and octet.pkcs1. Alternatives
are pkcs1_oaep, sslv23 and none. Note that none should
only be used if you implement cryptographically sound padding
modes in your application code as encrypting unpadded data with
RSA is insecure rsa_sign(+Key, +Data, -Signature, +Options) is detsha1, 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.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.
rsa_verify(+Key, +Data, +Signature, +Options) is semidetOptions:
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.hex. Alternatives
are octet, utf8 and text. crypto_data_decrypt(+CipherText, +Algorithm, +Key, +IV, -PlainText, +Options)utf8.
Alternatives are utf8 and octet.block. You can disable padding by supplying none here. crypto_data_encrypt(+PlainText, +Algorithm, +Key, +IV, -CipherText, +Options)PlainText must be a string, atom or list of codes or characters, and CipherText is created as a string. Key and IV are typically lists of bytes, though atoms and strings are also permitted. Algorithm must be an algorithm which your copy of OpenSSL knows about.
Keys and IVs can be chosen at random (using for example crypto_n_random_bytes/2) or derived from input keying material (IKM) using for example crypto_data_hkdf/4. This input is often a shared secret, such as a negotiated point on an elliptic curve, or the hash that was computed from a password via crypto_password_hash/3 with a freshly generated and specified salt.
Reusing the same combination of Key and IV typically leaks at least
some information about the plaintext. For example, identical
plaintexts will then correspond to identical ciphertexts. For some
algorithms, reusing an IV with the same Key has disastrous results
and can cause the loss of all properties that are otherwise
guaranteed. Especially in such cases, an IV is also called a
nonce (number used once). If an IV is not needed for your
algorithm (such as 'aes-128-ecb') then any value can be provided
as it will be ignored by the underlying implementation. Note that
such algorithms do not provide semantic security and are thus
insecure. You should use stronger algorithms instead.
It is safe to store and transfer the used initialization vector (or nonce) in plain text, but the key must be kept secret.
Commonly used algorithms include:
'chacha20-poly1305''aes-128-gcm''aes-128-cbc'Options:
utf8. Alternatives
are utf8 and octet.block. You can disable padding by supplying none here. If
padding is disabled for block ciphers, then the length of the
ciphertext must be a multiple of the block size.For example, with OpenSSL 1.1.0 and greater, we can use the ChaCha20 stream cipher with the Poly1305 authenticator. This cipher uses a 256-bit key and a 96-bit nonce, i.e., 32 and 12 bytes, respectively:
?- Algorithm = 'chacha20-poly1305',
crypto_n_random_bytes(32, Key),
crypto_n_random_bytes(12, IV),
crypto_data_encrypt("this is some input", Algorithm,
Key, IV, CipherText, [tag(Tag)]),
crypto_data_decrypt(CipherText, Algorithm,
Key, IV, RecoveredText, [tag(Tag)]).
Algorithm = 'chacha20-poly1305',
Key = [65, 147, 140, 197, 27, 60, 198, 50, 218|...],
IV = [253, 232, 174, 84, 168, 208, 218, 168, 228|...],
CipherText = <binary string>,
Tag = [248, 220, 46, 62, 255, 9, 178, 130, 250|...],
RecoveredText = "this is some input".
In this example, we use crypto_n_random_bytes/2 to generate a key and nonce from cryptographically secure random numbers. For repeated applications, you must ensure that a nonce is only used once together with the same key. Note that for authenticated encryption schemes, the tag that was computed during encryption is necessary for decryption. It is safe to store and transfer the tag in plain text.
crypto_modular_inverse(+X, +M, -Y) is det crypto_generate_prime(+N, -P, +Options) is dettrue (default is false), then a safe prime
is generated. This means that P is of the form 2*Q + 1 where Q
is also prime. crypto_is_prime(+P, +Options) is semidet crypto_name_curve(+Name, -Curve) is detprime256v1 and
secp256k1.
If you have OpenSSL installed, you can get a list of supported curves via:
$ openssl ecparam -list_curves
crypto_curve_order(+Curve, -Order) is det crypto_curve_generator(+Curve, -Point) is det crypto_curve_scalar_mult(+Curve, +N, +Point, -R) is det