object

crypto

Transport-neutral cryptographic helper predicates.

Availability:
logtalk_load(crypto(loader))
Author: Paulo Moura
Version: 1:2:0
Date: 2026-09-11
Compilation flags:
static, context_switching_calls, complements(restrict)
Uses:
base64url_no_padding
fast_random(Algorithm)
hmac
list
md5
os
type
Remarks:
(none)
Inherited public predicates:
 authenticated_channel_accept/5  authenticated_channel_decrypt/5  authenticated_channel_encrypt/5  authenticated_channel_finalize/3  authenticated_channel_initiate/4  chacha20_block/4  chacha20_encrypt/5  ed25519_keypair/2  ed25519_public_key/2  ed25519_sign/3  ed25519_verify/3  x25519_keypair/2  x25519_public_key/2  x25519_shared_secret/3  xchacha20/4  xchacha20_poly1305_decrypt/5  xchacha20_poly1305_encrypt/5  xchacha20_subkey_and_nonce/4

Public predicates

random_bytes/2

Returns a list with the requested number of random bytes. It tries /dev/urandom first and falls back to a pseudo-random generator when necessary.

Compilation flags:
static
Template:
random_bytes(Count,Bytes)
Mode and number of proofs:
random_bytes(+non_negative_integer,-list(byte)) - one_or_error
Exceptions:
Count is a variable:
instantiation_error
Count is neither a variable nor an integer:
type_error(integer,Count)
Count is an integer but is less than zero:
domain_error(non_negative_integer,Count)

token_hex/2

Returns a lowercase hexadecimal token generated from the requested number of random bytes.

Compilation flags:
static
Template:
token_hex(Count,Token)
Mode and number of proofs:
token_hex(+non_negative_integer,-atom) - one_or_error
Exceptions:
Count is a variable:
instantiation_error
Count is neither a variable nor an integer:
type_error(integer,Count)
Count is an integer but is less than zero:
domain_error(non_negative_integer,Count)

token_urlsafe/2

Returns an unpadded Base64URL token generated from the requested number of random bytes.

Compilation flags:
static
Template:
token_urlsafe(Count,Token)
Mode and number of proofs:
token_urlsafe(+non_negative_integer,-atom) - one_or_error
Exceptions:
Count is a variable:
instantiation_error
Count is neither a variable nor an integer:
type_error(integer,Count)
Count is an integer but is less than zero:
domain_error(non_negative_integer,Count)

random_below/2

Returns a uniformly distributed random integer greater than or equal to zero and less than the given exclusive upper bound.

Compilation flags:
static
Template:
random_below(UpperBound,Integer)
Mode and number of proofs:
random_below(+positive_integer,-non_negative_integer) - one_or_error
Exceptions:
UpperBound is a variable:
instantiation_error
UpperBound is neither a variable nor an integer:
type_error(integer,UpperBound)
UpperBound is an integer but is not positive:
domain_error(positive_integer,UpperBound)

hex_bytes/2

Relates a hexadecimal atom with the corresponding list of bytes, generating lowercase hexadecimal atoms when converting from bytes.

Compilation flags:
static
Template:
hex_bytes(Hex,Bytes)
Mode and number of proofs:
hex_bytes(+atom,-list(byte)) - zero_or_one_or_error
hex_bytes(-atom,+list(byte)) - zero_or_one_or_error
Exceptions:
Hex and Bytes are both variables:
instantiation_error
Hex is neither a variable nor an atom:
type_error(atom,Hex)
Hex is an atom but not a valid hexadecimal atom:
domain_error(hexadecimal_atom,Hex)
Bytes is neither a variable nor a list of bytes:
type_error(list(byte),Bytes)
Bytes contains a variable byte:
instantiation_error
Bytes contains a non-integer byte:
type_error(integer,Byte)
Bytes contains an integer outside the byte range:
domain_error(byte,Byte)

secure_compare/2

Succeeds when both inputs are equal using a constant-time comparison strategy for byte sequences of the same representation.

Compilation flags:
static
Template:
secure_compare(Expected,Candidate)
Mode and number of proofs:
secure_compare(+list(byte),+list(byte)) - zero_or_one_or_error
secure_compare(+atom,+atom) - zero_or_one_or_error
Exceptions:
Expected is a partial list or a list with an element which is a variable:
instantiation_error
Expected is neither an atom nor a list of bytes:
type_error(list(byte),Expected)
Expected is an atom and Candidate is not an atom:
type_error(atom,Candidate)
Candidate is a partial list or a list with an element which is a variable:
instantiation_error
Candidate is neither an atom nor a list of bytes when Expected is a byte list:
type_error(list(byte),Candidate)
Expected or Candidate contains a non-integer byte:
type_error(integer,Byte)
Expected or Candidate contains an integer outside the byte range:
domain_error(byte,Byte)

hkdf/5

Derives a byte sequence of the requested length from input keying material using HKDF with a hash object implementing the hash_digest_protocol protocol.

Compilation flags:
static
Template:
hkdf(Hash,KeyMaterial,Length,Bytes,Options)
Mode and number of proofs:
hkdf(+object_identifier,+list(byte),+non_negative_integer,-list(byte),+list(compound)) - one_or_error
Exceptions:
Hash is a variable:
instantiation_error
Hash is not an object implementing the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
KeyMaterial is a partial list or a list with an element which is a variable:
instantiation_error
KeyMaterial is a list but not a list of bytes:
type_error(list(byte),KeyMaterial)
KeyMaterial contains a non-integer byte:
type_error(integer,Byte)
KeyMaterial contains an integer outside the byte range:
domain_error(byte,Byte)
Length is a variable:
instantiation_error
Length is neither a variable nor an integer:
type_error(integer,Length)
Length is less than zero:
domain_error(non_negative_integer,Length)
Length exceeds the maximum HKDF output length for the selected hash:
domain_error(hkdf_output_length(0,MaxLength),Length)
Options is a partial list or a list with an element which is a variable:
instantiation_error
Options is neither a variable nor a list of compound terms:
type_error(list(compound),Options)
Options contains an invalid option term:
domain_error(hkdf_option,Option)
Options contains a salt/1 or info/1 value that is not a list of bytes:
type_error(list(byte),Bytes)
Options contains a salt/1 or info/1 value with a variable byte:
instantiation_error
Options contains a salt/1 or info/1 value with a non-integer byte:
type_error(integer,Byte)
Options contains a salt/1 or info/1 value with an integer outside the byte range:
domain_error(byte,Byte)
Remarks:

  • Repeated options: When the same HKDF option is given multiple times, the last occurrence is used.

  • Option salt(Bytes): Uses the given byte list as the HKDF salt. When this option is absent, the salt defaults to a zero-filled byte list with the selected hash digest size.

  • Option info(Bytes): Uses the given byte list as the HKDF context information. When this option is absent, the context information defaults to the empty list.

pbkdf2/6

Derives a key from a password byte sequence and a salt using PBKDF2 with a hash object implementing the hash_digest_protocol protocol.

Compilation flags:
static
Template:
pbkdf2(Hash,Password,Salt,Iterations,Length,DerivedKey)
Mode and number of proofs:
pbkdf2(+object_identifier,+list(byte),+list(byte),+integer,+positive_integer,-list(byte)) - one_or_error
Exceptions:
Hash is a variable:
instantiation_error
Hash is not an object implementing the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
Password is a partial list or a list with an element which is a variable:
instantiation_error
Password is a list but not a list of bytes:
type_error(list(byte),Password)
Password contains a non-integer element:
type_error(integer,Byte)
Password contains an integer outside the byte range:
domain_error(byte,Byte)
Salt is a partial list or a list with an element which is a variable:
instantiation_error
Salt is a liust but not a list of bytes:
type_error(list(byte),Salt)
Salt contains a non-integer element:
type_error(integer,Byte)
Salt contains an integer outside the byte range:
domain_error(byte,Byte)
Iterations is a variable:
instantiation_error
Iterations is neither a variable nor an integer:
type_error(integer,Iterations)
Iterations is an integer but not a positive integer:
domain_error(positive_integer,Iterations)
Length is a variable:
instantiation_error
Length is neither a variable nor an integer:
type_error(integer,Length)
Length is an integer but is not positive:
domain_error(positive_integer,Length)
Length exceeds the maximum PBKDF2 output length:
domain_error(pbkdf2_output_length,Length)

apr1/3

Computes the Apache APR1 encoded checksum for a password byte sequence and salt byte sequence.

Compilation flags:
static
Template:
apr1(Password,Salt,Checksum)
Mode and number of proofs:
apr1(+list(byte),+list(byte),-list(byte)) - one_or_error
Exceptions:
Password is a partial list or a list with an element which is a variable:
instantiation_error
Password is a list but not a list of bytes:
type_error(list(byte),Password)
Password contains a non-integer element:
type_error(integer,Byte)
Password contains an integer outside the byte range:
domain_error(byte,Byte)
Salt is a partial list or a list with an element which is a variable:
instantiation_error
Salt is a list but not a list of bytes:
type_error(list(byte),Salt)
Salt contains a non-integer element:
type_error(integer,Byte)
Salt contains an integer outside the byte range:
domain_error(byte,Byte)
Salt is not a valid APR1 salt:
domain_error(apr1_salt,Salt)

bcrypt/4

Computes a bcrypt version 2b encoded checksum for a password, cost, and raw 16-byte salt.

Compilation flags:
static
Template:
bcrypt(Password,Cost,Salt,Checksum)
Mode and number of proofs:
bcrypt(+list(byte),+integer,+list(byte),-list(byte)) - one_or_error
Exceptions:
Password is a partial list or a list with an element which is a variable:
instantiation_error
Password is a list but not a list of bytes:
type_error(list(byte),Password)
Password contains a non-integer element:
type_error(integer,Byte)
Password contains an integer outside the byte range:
domain_error(byte,Byte)
Password contains more than 72 bytes:
domain_error(bcrypt_password_length,Password)
Cost is a variable:
instantiation_error
Cost is not an integer:
type_error(integer,Cost)
Cost is outside the range 4 through 31:
domain_error(bcrypt_cost,Cost)
Salt is a partial list or a list with an element which is a variable:
instantiation_error
Salt is a list but not a list of bytes:
type_error(list(byte),Salt)
Salt is not exactly 16 bytes long:
domain_error(bcrypt_salt,Salt)

password_hash/4

Computes a structured password-hash term using the selected password-hashing method and derivation options.

Compilation flags:
static
Template:
password_hash(Method,Password,PasswordHash,Options)
Mode and number of proofs:
password_hash(+object_identifier,+list(byte),-compound,+list(compound)) - one_or_error
password_hash(+compound,+list(byte),-compound,+list(compound)) - one_or_error
Exceptions:
Method is not a ground term:
instantiation_error
Method is a ground Hash or pbkdf2(Hash) term but not an object implementing the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
Password is a partial list or a list with an element which is a variable:
instantiation_error
Password is a list but not a list of bytes:
type_error(list(byte),Password)
Password contains a non-integer element:
type_error(integer,Byte)
Password contains an integer outside the byte range:
domain_error(byte,Byte)
Password contains more than 72 bytes when using bcrypt:
domain_error(bcrypt_password_length,Password)
Options is a partial list or a list with an element which is a variable:
instantiation_error
Options is a list but not a list of compound terms:
type_error(list(compound),Options)
Options contains an invalid option term:
domain_error(password_hash_option,Option)
Options contains an iterations/1 value that is not an integer:
type_error(integer,Iterations)
Options contains an iterations/1 value that is not a positive integer:
domain_error(positive_integer,Iterations)
Options contains a cost/1 value that is not an integer:
type_error(integer,Cost)
Options contains a cost/1 value outside the range 4 through 31:
domain_error(bcrypt_cost,Cost)
Options contains a salt/1 value that is not a list of bytes:
type_error(list(byte),Salt)
Options contains a salt/1 value with a variable byte:
instantiation_error
Options contains a salt/1 value with a non-integer byte:
type_error(integer,Byte)
Options contains a salt/1 value with an integer outside the byte range:
domain_error(byte,Byte)
Options contains a bcrypt salt/1 value that is not exactly 16 bytes long:
domain_error(bcrypt_salt,Salt)
Options contains an invalid APR1 salt/1 value:
domain_error(apr1_salt,Salt)
Options contains a salt_length/1 or length/1 value that is not an integer:
type_error(integer,Length)
Options contains a PBKDF2 salt_length/1 value that is less than zero:
domain_error(non_negative_integer,Length)
Options contains an APR1 salt_length/1 value outside the range 1 through 8:
domain_error(apr1_salt_length,Length)
Options contains a length/1 value that is not positive:
domain_error(positive_integer,Length)
Options selects a PBKDF2 length/1 value that exceeds the maximum output length:
domain_error(pbkdf2_output_length,Length)
Remarks:

  • Method: Supported methods are pbkdf2(Hash), bcrypt, and apr1. A hash object is interpreted as shorthand for pbkdf2(Hash).

  • Repeated options: When the same password-hash option is given multiple times, the last occurrence is used.

  • Option iterations(Count): Uses the given positive integer PBKDF2 iteration count. When this option is absent, the iteration count defaults to 131072.

  • Option cost(Count): Uses the given bcrypt cost from 4 through 31. When this option is absent, the cost defaults to 12.

  • Option salt(Bytes): Uses the given method-specific salt. Bcrypt requires exactly 16 raw bytes; APR1 requires one through eight characters from its base64 alphabet.

  • Option salt_length(Count): Generates a random PBKDF2 or APR1 salt when salt/1 is absent. PBKDF2 defaults to 16 bytes and APR1 defaults to 8 characters.

  • Option length(Count): Uses the given positive PBKDF2 derived-key length. When this option is absent, the derived-key length defaults to the selected hash digest size.

password_hash_needs_rehash/3

Succeeds when the given password-hash term does not match the selected password-hashing method and policy.

Compilation flags:
static
Template:
password_hash_needs_rehash(PasswordHash,Method,Options)
Mode and number of proofs:
password_hash_needs_rehash(+compound,+object_identifier,+list(compound)) - zero_or_one_or_error
password_hash_needs_rehash(+compound,+compound,+list(compound)) - zero_or_one_or_error
Exceptions:
PasswordHash is not a supported password-hash term:
domain_error(password_hash,PasswordHash)
PasswordHash contains a variable hash object:
instantiation_error
PasswordHash contains a hash object that does not implement the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
PasswordHash contains an Iterations value that is not an integer:
type_error(integer,Iterations)
PasswordHash contains an Iterations value that is not a positive integer:
domain_error(positive_integer,Iterations)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value that is not a list of bytes:
type_error(list(byte),Bytes)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with a variable byte:
instantiation_error
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with a non-integer byte:
type_error(integer,Byte)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with an integer outside the byte range:
domain_error(byte,Byte)
PasswordHash contains an invalid APR1 salt:
domain_error(apr1_salt,Salt)
PasswordHash contains an invalid APR1 checksum:
domain_error(apr1_checksum,Checksum)
PasswordHash contains a bcrypt cost that is not an integer:
type_error(integer,Cost)
PasswordHash contains a bcrypt cost outside the range 4 through 31:
domain_error(bcrypt_cost,Cost)
PasswordHash contains a bcrypt salt that is not exactly 16 bytes long:
domain_error(bcrypt_salt,Salt)
PasswordHash contains an invalid bcrypt checksum:
domain_error(bcrypt_checksum,Checksum)
Method is not a ground term:
instantiation_error
Method is a ground Hash or pbkdf2(Hash) term but not an object implementing the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
Options is a partial list or a list with an element which is a variable:
instantiation_error
Options is a list but not a list of compound terms:
type_error(list(compound),Options)
Options contains an invalid option term:
domain_error(password_hash_option,Option)
Options contains an iterations/1 value that is not an integer:
type_error(integer,Iterations)
Options contains an iterations/1 value that is not a positive integer:
domain_error(positive_integer,Iterations)
Options contains a cost/1 value that is not an integer:
type_error(integer,Cost)
Options contains a cost/1 value outside the range 4 through 31:
domain_error(bcrypt_cost,Cost)
Options contains a salt/1 value that is not a list of bytes:
type_error(list(byte),Salt)
Options contains a salt/1 value with a variable byte:
instantiation_error
Options contains a salt/1 value with a non-integer byte:
type_error(integer,Byte)
Options contains a salt/1 value with an integer outside the byte range:
domain_error(byte,Byte)
Options contains a bcrypt salt/1 value that is not exactly 16 bytes long:
domain_error(bcrypt_salt,Salt)
Options contains an invalid APR1 salt/1 value:
domain_error(apr1_salt,Salt)
Options contains a salt_length/1 or length/1 value that is not an integer:
type_error(integer,Length)
Options contains a PBKDF2 salt_length/1 value that is less than zero:
domain_error(non_negative_integer,Length)
Options contains an APR1 salt_length/1 value outside the range 1 through 8:
domain_error(apr1_salt_length,Length)
Options contains a length/1 value that is not positive:
domain_error(positive_integer,Length)
Options selects a PBKDF2 length/1 value that exceeds the maximum output length:
domain_error(pbkdf2_output_length,Length)
Remarks:

  • Method: Supported target methods are pbkdf2(Hash), bcrypt, and apr1. A hash object is interpreted as shorthand for pbkdf2(Hash).

  • Policy: The Method and Options arguments use the same method and policy options as password_hash/4.

  • Method changes: A valid stored hash using a different method always needs rehashing.

verify_password_hash/2

Succeeds when the password byte sequence matches the given structured password-hash term or stored digest term.

Compilation flags:
static
Template:
verify_password_hash(PasswordHash,Password)
Mode and number of proofs:
verify_password_hash(+compound,+list(byte)) - zero_or_one_or_error
Exceptions:
PasswordHash is not a ground term:
instantiation_error
PasswordHash is not a supported password-hash term:
domain_error(password_hash,PasswordHash)
PasswordHash contains a variable hash object:
instantiation_error
PasswordHash contains a hash object that does not implement the hash_digest_protocol protocol:
domain_error(crypto_hash,Hash)
PasswordHash contains an Iterations value that is not an integer:
type_error(integer,Iterations)
PasswordHash contains an Iterations value that is not a positive integer:
domain_error(positive_integer,Iterations)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value that is not a list of bytes:
type_error(list(byte),Bytes)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with a variable byte:
instantiation_error
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with a non-integer byte:
type_error(integer,Byte)
PasswordHash contains a Salt, StoredKey, StoredDigest, or Checksum value with an integer outside the byte range:
domain_error(byte,Byte)
PasswordHash contains an invalid APR1 salt:
domain_error(apr1_salt,Salt)
PasswordHash contains an invalid APR1 checksum:
domain_error(apr1_checksum,Checksum)
Password is a partial list or a list with an element which is a variable:
instantiation_error
Password is a list but not a list of bytes:
type_error(list(byte),Password)
Password contains a non-integer element:
type_error(integer,Byte)
Password contains an integer outside the byte range:
domain_error(byte,Byte)

password_hash_atom/2

Converts between a structured bcrypt 2b or APR1 password-hash term and its canonical modular-crypt atom.

Compilation flags:
static
Template:
password_hash_atom(PasswordHash,Atom)
Mode and number of proofs:
password_hash_atom(+compound,?atom) - zero_or_one_or_error
password_hash_atom(-compound,+atom) - one_or_error
Exceptions:
Both arguments are variables:
instantiation_error
Atom is neither a variable nor an atom:
type_error(atom,Atom)
The instantiated argument does not represent a supported canonical password hash:
domain_error(password_hash,Value)

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

xor_bytes/3

Computes the byte-wise exclusive disjunction of two equal-length byte lists.

Compilation flags:
static
Template:
xor_bytes(Bytes1,Bytes2,XorBytes)
Mode and number of proofs:
xor_bytes(+list(byte),+list(byte),-list(byte)) - one

constant_time_equal/2

Compares two byte lists using a constant-time strategy.

Compilation flags:
static
Template:
constant_time_equal(Expected,Candidate)
Mode and number of proofs:
constant_time_equal(+list(byte),+list(byte)) - zero_or_one

Operators

(none)