crypto.pl -- Cryptography and authentication library
This 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_data_hash(+Data, -Hash, +Options) is det
- Hash is the hash of Data. The conversion is controlled
by Options:
- algorithm(+Algorithm)
- One of
md5
,sha1
,sha224
,sha256
(default),sha384
,sha512
,blake2s256
orblake2b512
. TheBLAKE
digest algorithms require OpenSSL 1.1.0 or greater. - encoding(+Encoding)
- If Data is a sequence of character codes, this must be
translated into a sequence of bytes, because that is what
the hashing requires. The default encoding is
utf8
. The other meaningful value isoctet
, claiming that Data contains raw bytes. - hmac(+Key)
- If this option is specified, a hash-based message authentication code (HMAC) is computed, using the specified Key which is either an atom or string. Any of the available digest algorithms can be used with this option. The cryptographic strength of the HMAC depends on that of the chosen algorithm and also on the key. This option requires OpenSSL 1.1.0 or greater.
- crypto_file_hash(+File, -Hash, +Options) is det
- True if Hash is the hash of the content of File. For Options, see crypto_data_hash/3.
- crypto_context_new(-Context, +Options) is det
- Context is unified with the empty context, taking into account Options. The context can be used in crypto_data_context/3. For Options, see crypto_data_hash/3.
- crypto_data_context(+Data, +Context0, -Context) is det
- Context0 is an existing computation context, and Context is the
new context after hashing Data in addition to the previously
hashed data. Context0 may be produced by a prior invocation of
either crypto_context_new/2 or crypto_data_context/3 itself.
This 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)
- Obtain the hash code of Context. Hash is an atom representing the hash code that is associated with the current state of the computation context Context.
- crypto_open_hash_stream(+OrgStream, -HashStream, +Options) is det
- Open a filter stream on OrgStream that maintains a hash. The hash
can be retrieved at any time using crypto_stream_hash/2. Available
Options in addition to those of crypto_data_hash/3 are:
- close_parent(+Bool)
- If
true
(default), closing the filter stream also closes the original (parent) stream.
- crypto_stream_hash(+HashStream, -Hash) is det
- Unify Hash with a hash for the bytes sent to or read from HashStream. Note that the hash is computed on the stream buffers. If the stream is an output stream, it is first flushed and the Digest represents the hash at the current location. If the stream is an input stream the Digest represents the hash of the processed input including the already buffered data.
- 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 areoctet
,utf8
andtext
.
- ecdsa_verify(+Key, +Data, +Signature, +Options) is semidet
- 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 areoctet
,utf8
andtext
.
- hex_bytes(?Hex, ?List) is det
- Relation between a hexadecimal sequence and a list of bytes. Hex
is an atom, string, list of characters or list of codes in
hexadecimal encoding. This is the format that is used by
crypto_data_hash/3 and related predicates to represent hashes.
Bytes is a list of integers between 0 and 255 that represent the
sequence as a list of bytes. At least one of the arguments must
be instantiated. When converting List to Hex, an atom is used
to represent the sequence of hexadecimal digits.
Example:
?- 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 det
- RSA Public key encryption and decryption primitives. A string
can be safely communicated by first encrypting it and have the
peer decrypt it with the matching key and predicate. The length
of the string is limited by the key length.
Options:
- encoding(+Encoding)
- Encoding to use for Data. Default is
utf8
. Alternatives areutf8
andoctet
. - padding(+PaddingScheme)
- Padding scheme to use. Default is
pkcs1
. Alternatives arepkcs1_oaep
,sslv23
andnone
. Note thatnone
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 det
- 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
orsha512
. - encoding(+Encoding)
- Encoding to use for Data. Default is
hex
. Alternatives areoctet
,utf8
andtext
.
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 semidet
- 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
orsha512
. - encoding(+Encoding)
- Encoding to use for Data. Default is
hex
. Alternatives areoctet
,utf8
andtext
.
- evp_decrypt(+CipherText, +Algorithm, +Key, +IV, -PlainText, +Options)
- Decrypt the given CipherText, using the symmetric algorithm
Algorithm, key Key, and iv IV, to give PlainText. CipherText, Key
and IV should all be strings, and PlainText is created as a string
as well. Algorithm should be an algorithm which your copy of OpenSSL
knows about. Examples are:
- aes-128-cbc
- aes-256-cbc
- des3
If the IV is not needed for your decryption algorithm (such as aes-128-ecb) then any string can be provided as it will be ignored by the underlying implementation
Options:
- encoding(+Encoding)
- Encoding to use for Data. Default is
utf8
. Alternatives areutf8
andoctet
. - padding(+PaddingScheme)
- Padding scheme to use. Default is
block
. You can disable padding by supplyingnone
here.
Example of aes-128-cbc encryption:
?- evp_encrypt("this is some input", 'aes-128-cbc', "sixteenbyteofkey", "sixteenbytesofiv", CipherText, []), evp_decrypt(CipherText, 'aes-128-cbc', "sixteenbyteofkey", "sixteenbytesofiv", RecoveredText, []). CipherText = <binary string> RecoveredText = "this is some input".
- evp_encrypt(+PlainText, +Algorithm, +Key, +IV, -CipherTExt, +Options)
- Encrypt the given PlainText, using the symmetric algorithm Algorithm, key Key, and iv IV, to give CipherText. See evp_decrypt/6.
- 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 det
- RSA Public key encryption and decryption primitives. A string
can be safely communicated by first encrypting it and have the
peer decrypt it with the matching key and predicate. The length
of the string is limited by the key length.
Options:
- encoding(+Encoding)
- Encoding to use for Data. Default is
utf8
. Alternatives areutf8
andoctet
. - padding(+PaddingScheme)
- Padding scheme to use. Default is
pkcs1
. Alternatives arepkcs1_oaep
,sslv23
andnone
. Note thatnone
should only be used if you implement cryptographically sound padding modes in your application code as encrypting unpadded data with RSA is insecure
- 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 det
- RSA Public key encryption and decryption primitives. A string
can be safely communicated by first encrypting it and have the
peer decrypt it with the matching key and predicate. The length
of the string is limited by the key length.
Options:
- encoding(+Encoding)
- Encoding to use for Data. Default is
utf8
. Alternatives areutf8
andoctet
. - padding(+PaddingScheme)
- Padding scheme to use. Default is
pkcs1
. Alternatives arepkcs1_oaep
,sslv23
andnone
. Note thatnone
should only be used if you implement cryptographically sound padding modes in your application code as encrypting unpadded data with RSA is insecure
- 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 det
- RSA Public key encryption and decryption primitives. A string
can be safely communicated by first encrypting it and have the
peer decrypt it with the matching key and predicate. The length
of the string is limited by the key length.
Options:
- encoding(+Encoding)
- Encoding to use for Data. Default is
utf8
. Alternatives areutf8
andoctet
. - padding(+PaddingScheme)
- Padding scheme to use. Default is
pkcs1
. Alternatives arepkcs1_oaep
,sslv23
andnone
. Note thatnone
should only be used if you implement cryptographically sound padding modes in your application code as encrypting unpadded data with RSA is insecure