head 1.8; access; symbols; locks ulrich:1.8; strict; comment @# @; 1.8 date 2024.03.22.17.54.08; author ulrich; state Exp; branches; next 1.7; 1.7 date 2024.03.21.15.12.51; author ulrich; state Exp; branches; next 1.6; 1.6 date 2024.03.19.18.45.07; author ulrich; state Exp; branches; next 1.5; 1.5 date 2024.03.15.09.50.32; author ulrich; state Exp; branches; next 1.4; 1.4 date 2024.03.13.20.18.05; author ulrich; state Exp; branches; next 1.3; 1.3 date 2024.03.12.08.58.21; author ulrich; state Exp; branches; next 1.2; 1.2 date 2024.03.11.06.52.30; author ulrich; state Exp; branches; next 1.1; 1.1 date 2024.03.11.06.48.32; author ulrich; state Exp; branches; next ; desc @@ 1.8 log @*** empty log message *** @ text @ crypto_data_hash/3

crypto_data_hash/3

Markus Triska
This draft is for consideration of inclusion into the Prolog prologue. References refer to 13211-1:1995. Parts needing improvements are underlined.

p.c.x crypto_data_hash/3

p.c.x.1 Description

crypto_data_hash(Cs, Hs, Options) is true iff Hs is a list of characters '0','1',...'9',a,b,c,d,e,f denoting the Base16-encoding of a cryptographic hash of the characters Cs, taking into account the list Options of crypto_data_hash-options. Direct unification of Hs with a computed result may leak information about the expected hash or HMAC.

Options:

algorithm(A)
Use hash algorithm A, either a variable or one of sha256, sha384, or sha512. If A is a variable, then an implementation-dependent algorithm I is used, and A is unified with I.
encoding(E)
Encoding E to use for interpreting each character of Cs as a sequence of bytes, either utf8 for UTF-8 encoding, or octet to use the character code of each character as byte value.
hmac(Bs)
Hs is a hash-based message authentication code (HMAC) of Cs, using the list of bytes Bs as key. The construction is specified in RFC 2104.

p.c.x.2 Template and modes

crypto_data_hash(+character_list, -character_list, +crypto_data_hash_options_list)

p.c.x.3 Errors

a) Cs is a partial list or a list with an element E which is a variable
instantiation_error.
b) Options is a partial list or has a list prefix with an element E which is a variable
instantiation_error.
c) Cs is neither a list nor a partial list.
type_error(list, Cs).
d) Cs is a ground list with an element E which is not a character
type_error(character, E).
e) Options is neither a partial list nor a list
type_error(list, Options).
f) Options is a list with an element E which is neither a variable nor a valid option
domain_error(crypto_data_hash_option, E).
g) Hs is neither a list nor a partial list.
type_error(list, Hs).
h) Hs has a list prefix with an element E which is not a character
type_error(character, E).

p.c.x.4 Examples

?- crypto_data_hash("test", Hs, [algorithm(sha256)]).
   Hs = "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08".

History

2017-01-04: first availability in SWI-Prolog, with hmac/1 option as later addition
2020-05-13: first availability in Scryer Prolog, with encoding/1 and hmac/1 options as later additions
2023-11-14: first traceable availability in Trealla Prolog
@ 1.7 log @*** empty log message *** @ text @d81 3 a83 1 the list Options of crypto_data_hash-options. d90 1 a90 1
algorithm(A) Use hash algorithm A, either d95 2 a96 3
encoding(E) Encoding E to use for d101 5 a105 11
hmac(Bs) Hs is a hash-based message authentication code (HMAC) of Cs, using the list of bytes Bs as key. The construction is specified in RFC 2104.
NOTE — Direct unification of Hs with a computed result may leak information about the expected hash or HMAC. @ 1.6 log @*** empty log message *** @ text @d93 2 a94 1 d100 2 a101 1 a106 1 @ 1.5 log @*** empty log message *** @ text @d92 1 a92 1 and A is unified with I. d95 15 a109 2 interpreting Cs as bytes, either utf8 or octet. d114 1 a114 1 crypto_data_hash(+character_list, -character_list, +crypto_data_hash_options_list). d124 1 a124 1
b) Options is a partial list or a list with an element d133 1 a133 1
d) Cs is a ground list that contains an element E which is not a character d141 2 a142 2
f) An element E of the Options list is neither a variable nor a valid option d150 4 d165 8 @ 1.4 log @*** empty log message *** @ text @a77 5 crypto_data_hash(Cs, Hs, Options) is true if Hs is the cryptographic hash of the characters Cs.

More precisely, d80 1 a80 1 the cryptographic hash of the characters Cs, taking into account @ 1.3 log @*** empty log message *** @ text @d79 1 a79 1 cryptographic hash of the characters Cs. d85 2 a86 2 the cryptographic hash of the characters Cs, taking into account Options. d106 1 a106 1 crypto_data_hash(+character_list, -character_list, +options_list). @ 1.2 log @*** empty log message *** @ text @d121 1 a121 1

c) Cs is neither a list nor partial list. d138 1 a138 1
g) Hs is neither a list nor partial list. @ 1.1 log @Initial revision @ text @d106 1 a106 1 crypto_data_hash(+list, -list, +options_list). d112 1 a112 1
a) Cs is not ground d121 1 a121 1
c) Cs is ground and not a list. d136 5 a140 1
domain_error(crypto_data_hash_option, E). @