Difference between revisions of "Hashing Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] contains cryptographic hash functions.
+
This [[Module Library|XQuery Module]] provides functions that perform different hash operations.
  
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the {{Code|http://basex.org/modules/hash}} namespace, which is statically bound to the {{Code|hash}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/hash</nowiki></code> namespace, which is statically bound to the {{Code|hash}} prefix.<br/>
−
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
  
 
==hash:md5==
 
==hash:md5==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|hash:md5|$value as xs:anyAtomicType|xs:base64Binary}}<br />
+
|<pre>hash:md5(
−
|-
+
  $value as xs:anyAtomicType
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Computes the MD5 hash of the given {{Code|$value}}, which may be a string or a binary item (xs:base64Binary, xs:hexBinary).
+
|Computes the MD5 hash of the given {{Code|$value}}, which may be of type {{Code|xs:string}}, {{Code|xs:base64Binary}}, or {{Code|xs:hexBinary}}.
−
|-
+
|- valign="top"
−
| '''Errors'''
 
−
|{{Error|FORG0006|XQuery Errors#Function Errors}} the specified value is neither a string nor a binary item.
 
−
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|xs:hexBinary(hash:md5("BaseX"))}} returns {{Code|0D65185C9E296311C0A2200179E479A2}}.
+
* {{Code|string(xs:hexBinary(hash:md5("BaseX")))}} returns {{Code|0D65185C9E296311C0A2200179E479A2}}.
−
* {{Code|hash:md5(xs:base64Binary(""))}} returns {{Code|1B2M2Y8AsgTpgAmY7PhCfg==}}.
+
* {{Code|string(hash:md5(xs:base64Binary("")))}} returns <code>1B2M2Y8AsgTpgAmY7PhCfg==</code>.
 
|}
 
|}
  
 
==hash:sha1==
 
==hash:sha1==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|hash:sha1|$value as xs:anyAtomicType|xs:base64Binary}}<br />
+
|<pre>hash:sha1(
−
|-
+
  $value as xs:anyAtomicType
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Computes the SHA-1 hash of the given {{Code|$value}}, which may be a string or a binary item (xs:base64Binary, xs:hexBinary).
+
|Computes the SHA-1 hash of the given {{Code|$value}}, which may be of type {{Code|xs:string}}, {{Code|xs:base64Binary}}, or {{Code|xs:hexBinary}}.
−
|-
+
|- valign="top"
−
| '''Errors'''
 
−
|{{Error|FORG0006|XQuery Errors#Function Errors}} the specified value is neither a string nor a binary item.
 
−
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|xs:hexBinary(hash:sha1("BaseX"))}} returns {{Code|3AD5958F0F27D5AFFDCA2957560F121D0597A4ED}}.
+
* {{Code|string(xs:hexBinary(hash:sha1("BaseX")))}} returns {{Code|3AD5958F0F27D5AFFDCA2957560F121D0597A4ED}}.
−
* {{Code|hash:sha1(xs:base64Binary(""))}} returns {{Code|2jmj7l5rSw0yVb/vlWAYkK/YBwk=}}.
+
* {{Code|string(hash:sha1(xs:base64Binary("")))}} returns <code>2jmj7l5rSw0yVb/vlWAYkK/YBwk=</code>.
 
|}
 
|}
  
 
==hash:sha256==
 
==hash:sha256==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|hash:sha256|$value as xs:anyAtomicType|xs:base64Binary}}<br />
+
|<pre>hash:sha256(
−
|-
+
  $value as xs:anyAtomicType
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Computes the SHA-256 hash of the given {{Code|$value}}, which may be a string or a binary item (xs:base64Binary, xs:hexBinary).
+
|Computes the SHA-256 hash of the given {{Code|$value}}, which may be of type {{Code|xs:string}}, {{Code|xs:base64Binary}}, or {{Code|xs:hexBinary}}.
−
|-
+
|- valign="top"
−
| '''Errors'''
 
−
|{{Error|FORG0006|XQuery Errors#Function Errors}} the specified value is neither a string nor a binary item.
 
−
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|xs:hexBinary(hash:sha256("BaseX"))}} returns {{Code|15D570763DEB75D728BB69643392873B835CCCC94A2F1E881909DA47662821A3}}.
+
* {{Code|string(xs:hexBinary(hash:sha256("BaseX")))}} returns {{Code|15D570763DEB75D728BB69643392873B835CCCC94A2F1E881909DA47662821A3}}.
−
* {{Code|hash:sha256(xs:base64Binary(""))}} returns {{Code|47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=}}.
+
* {{Code|string(hash:sha256(xs:base64Binary("")))}} returns <code>47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=</code>.
 
|}
 
|}
  
 
==hash:hash==
 
==hash:hash==
−
{|
+
{| width='100%'
−
|-
+
|- valign="top"
−
| width='90' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|hash:hash|$value as xs:anyAtomicType, $algorithm as xs:string|xs:base64Binary}}<br />
+
|<pre>hash:hash(
−
|-
+
  $value     as xs:anyAtomicType,
 +
  $algorithm as xs:string
 +
) as xs:base64Binary</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Computes the hash of the given {{Code|$value}}, using the specified {{Code|$algorithm}}. The specified values may be a string or a binary item (xs:base64Binary, xs:hexBinary)<br />The following three algorihms are supported: {{Code|MD5}}, {{Code|SHA-1}}, and {{Code|SHA-256}}.
+
|Computes the hash of the given {{Code|$value}}, using the specified {{Code|$algorithm}}. The specified values may be of type {{Code|xs:string}}, {{Code|xs:base64Binary}}, or {{Code|xs:hexBinary}}.<br/>The following three algorithms are supported: {{Code|MD5}}, {{Code|SHA-1}}, and {{Code|SHA-256}}.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|HASH0001|#Errors}} the specified hashing algorithm is unknown.<br/>{{Error|FORG0006|XQuery Errors#Function Errors}} the specified value is neither a string nor a binary item.
+
|{{Error|algorithm|#Errors}} the specified hashing algorithm is unknown.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|xs:hexBinary(hash:md5("", "MD5"))}} returns {{Code|D41D8CD98F00B204E9800998ECF8427E}}.
+
* {{Code|string(xs:hexBinary(hash:hash("", "MD5")))}} returns {{Code|D41D8CD98F00B204E9800998ECF8427E}}.
−
* {{Code|hash:md5("", "")}} raises an error.
+
* {{Code|string(hash:hash("", ""))}} raises an error, because no algorithm was specified.
 
|}
 
|}
  
Line 83: Line 82:
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="5%"|Code
+
! width="110"|Code
−
! width="95%"|Description
+
|Description
−
|-
+
|- valign="top"
−
|{{Code|HASH0001}}
+
|{{Code|algorithm}}
−
|The specified hashing algorithm is unknown.
+
|The specified hash algorithm is unknown.
 
|}
 
|}
  
 
=Changelog=
 
=Changelog=
  
−
This module was introduced with Version 7.3.
+
;Version 9.0
 +
 
 +
* Updated: error codes updated; errors now use the module namespace
  
−
[[Category:XQuery]]
+
The module was introduced with Version 7.3.

Latest revision as of 15:30, 9 March 2023

This XQuery Module provides functions that perform different hash operations.

Conventions[edit]

All functions and errors in this module are assigned to the http://basex.org/modules/hash namespace, which is statically bound to the hash prefix.

Functions[edit]

hash:md5[edit]

Signature 
hash:md5(
  $value  as xs:anyAtomicType
) as xs:base64Binary
Summary Computes the MD5 hash of the given $value, which may be of type xs:string, xs:base64Binary, or xs:hexBinary.
Examples
  • string(xs:hexBinary(hash:md5("BaseX"))) returns 0D65185C9E296311C0A2200179E479A2.
  • string(hash:md5(xs:base64Binary(""))) returns 1B2M2Y8AsgTpgAmY7PhCfg==.

hash:sha1[edit]

Signature 
hash:sha1(
  $value  as xs:anyAtomicType
) as xs:base64Binary
Summary Computes the SHA-1 hash of the given $value, which may be of type xs:string, xs:base64Binary, or xs:hexBinary.
Examples
  • string(xs:hexBinary(hash:sha1("BaseX"))) returns 3AD5958F0F27D5AFFDCA2957560F121D0597A4ED.
  • string(hash:sha1(xs:base64Binary(""))) returns 2jmj7l5rSw0yVb/vlWAYkK/YBwk=.

hash:sha256[edit]

Signature 
hash:sha256(
  $value  as xs:anyAtomicType
) as xs:base64Binary
Summary Computes the SHA-256 hash of the given $value, which may be of type xs:string, xs:base64Binary, or xs:hexBinary.
Examples
  • string(xs:hexBinary(hash:sha256("BaseX"))) returns 15D570763DEB75D728BB69643392873B835CCCC94A2F1E881909DA47662821A3.
  • string(hash:sha256(xs:base64Binary(""))) returns 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=.

hash:hash[edit]

Signature 
hash:hash(
  $value      as xs:anyAtomicType,
  $algorithm  as xs:string
) as xs:base64Binary
Summary Computes the hash of the given $value, using the specified $algorithm. The specified values may be of type xs:string, xs:base64Binary, or xs:hexBinary.
The following three algorithms are supported: MD5, SHA-1, and SHA-256.
Errors algorithm: the specified hashing algorithm is unknown.
Examples
  • string(xs:hexBinary(hash:hash("", "MD5"))) returns D41D8CD98F00B204E9800998ECF8427E.
  • string(hash:hash("", "")) raises an error, because no algorithm was specified.

Errors[edit]

Code Description
algorithm The specified hash algorithm is unknown.

Changelog[edit]

Version 9.0
  • Updated: error codes updated; errors now use the module namespace

The module was introduced with Version 7.3.

Retrieved from "https://old.docs.basex.org/index.php?title=Hashing_Module&oldid=16442"