| Did you know ... | Search Documentation: |
| Pack logtalk -- logtalk-3.102.0/docs/apis/_sources/crypto_0.rst.txt |
.. index:: single: crypto .. _crypto/0:
.. rst-class:: right
object
cryptoTransport-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:
| :ref:`base64url_no_padding <base64url_no_padding/0>`
| :ref:`fast_random(Algorithm) <fast_random/1>`
| :ref:`hmac <hmac/0>`
| :ref:`list <list/0>`
| :ref:`md5 <md5/0>`
| :ref:`os <os/0>`
| :ref:`type <type/0>`
| Remarks: | (none)
| Inherited public predicates: | Â :ref:`authenticated_channel/0::authenticated_channel_accept/5` Â :ref:`authenticated_channel/0::authenticated_channel_decrypt/5` Â :ref:`authenticated_channel/0::authenticated_channel_encrypt/5` Â :ref:`authenticated_channel/0::authenticated_channel_finalize/3` Â :ref:`authenticated_channel/0::authenticated_channel_initiate/4` Â :ref:`xchacha20_poly1305/0::chacha20_block/4` Â :ref:`xchacha20_poly1305/0::chacha20_encrypt/5` Â :ref:`ed25519/0::ed25519_keypair/2` Â :ref:`ed25519/0::ed25519_public_key/2` Â :ref:`ed25519/0::ed25519_sign/3` Â :ref:`ed25519/0::ed25519_verify/3` Â :ref:`x25519/0::x25519_keypair/2` Â :ref:`x25519/0::x25519_public_key/2` Â :ref:`x25519/0::x25519_shared_secret/3` Â :ref:`xchacha20_poly1305/0::xchacha20/4` Â :ref:`xchacha20_poly1305/0::xchacha20_poly1305_decrypt/5` Â :ref:`xchacha20_poly1305/0::xchacha20_poly1305_encrypt/5` Â :ref:`xchacha20_poly1305/0::xchacha20_subkey_and_nonce/4` Â
.. contents:: :local: :backlinks: top
.. index:: random_bytes/2 .. _crypto/0::random_bytes/2:
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)
.. index:: token_hex/2 .. _crypto/0::token_hex/2:
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)
.. index:: token_urlsafe/2 .. _crypto/0::token_urlsafe/2:
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)
.. index:: random_below/2 .. _crypto/0::random_below/2:
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)
.. index:: hex_bytes/2 .. _crypto/0::hex_bytes/2:
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)
.. index:: secure_compare/2 .. _crypto/0::secure_compare/2:
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)
.. index:: hkdf/5 .. _crypto/0::hkdf/5:
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:
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.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... index:: pbkdf2/6 .. _crypto/0::pbkdf2/6:
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)
.. index:: apr1/3 .. _crypto/0::apr1/3:
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)
.. index:: bcrypt/4 .. _crypto/0::bcrypt/4:
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)
.. index:: password_hash/4 .. _crypto/0::password_hash/4:
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:
pbkdf2(Hash), bcrypt, and apr1. A hash object is interpreted as shorthand for pbkdf2(Hash).iterations(Count): Uses the given positive integer PBKDF2 iteration count. When this option is absent, the iteration count defaults to 131072.cost(Count): Uses the given bcrypt cost from 4 through 31. When this option is absent, the cost defaults to 12.salt(Bytes): Uses the given method-specific salt. Bcrypt requires exactly 16 raw bytes; APR1 requires one through eight characters from its base64 alphabet.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.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... index:: password_hash_needs_rehash/3 .. _crypto/0::password_hash_needs_rehash/3:
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:
pbkdf2(Hash), bcrypt, and apr1. A hash object is interpreted as shorthand for pbkdf2(Hash).Method and Options arguments use the same method and policy options as password_hash/4... index:: verify_password_hash/2 .. _crypto/0::verify_password_hash/2:
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)
.. index:: password_hash_atom/2 .. _crypto/0::password_hash_atom/2:
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)
(no local declarations; see entity ancestors if any)
.. index:: xor_bytes/3 .. _crypto/0::xor_bytes/3:
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
.. index:: constant_time_equal/2 .. _crypto/0::constant_time_equal/2:
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
(none)