Difference between revisions of "Cryptographic Module"

From BaseX Documentation
Jump to navigation Jump to search
(34 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
This [[Module Library|XQuery Module]] contains functions to perform cryptographic operations in XQuery.  
 
This [[Module Library|XQuery Module]] contains functions to perform cryptographic operations in XQuery.  
The cryptographic module is based on an early draft of the [http://expath.org/spec/crypto EXPath Cryptographic Module] and provides the following functionality: creation of message authentication codes (HMAC), encryption and decryption, and creation and validation of XML Digital Signatures.
+
The cryptographic module is based on an early draft of the [http://expath.org/spec/crypto/20110810 EXPath Cryptographic Module] and provides the following functionality: creation of message authentication codes (HMAC), encryption and decryption, and creation and validation of XML Digital Signatures.
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://expath.org/ns/crypto}} namespace, which is statically bound to the {{Code|crypto}} prefix.<br/>
+
All functions in this module are assigned to the <code><nowiki>http://expath.org/ns/crypto</nowiki></code> namespace, which is statically bound to the {{Code|crypto}} prefix.<br/>
All errors are assigned to the {{Code|http://expath.org/ns/error}} namespace, which is statically bound to the {{Code|experr}} prefix.
+
All errors are assigned to the <code><nowiki>http://expath.org/ns/error</nowiki></code> namespace, which is statically bound to the {{Code|experr}} prefix.
  
 
=Message Authentication=
 
=Message Authentication=
  
 
==crypto:hmac==
 
==crypto:hmac==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|crypto:hmac|$message as xs:string, $key as xs:string, $algorithm as xs:string|xs:string}}<br/>{{Func|crypto:hmac|$message as xs:string, $key as xs:string, $algorithm as xs:string, $encoding as xs:string|xs:string}}
+
|{{Func|crypto:hmac|$data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string|xs:string}}<br/>{{Func|crypto:hmac|$data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string, $encoding as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Creates a message authentication code via a cryptographic hash function and a secret {{Code|$key}}. <br/>
+
|Creates an authentication code for the specified {{Code|$data}} via a cryptographic hash function:
{{Code|$encoding}} must either be {{Code|hex}}, {{Code|base64}} or the empty string and specifies the encoding of the returned authentication code. '''Default is {{Code|base64}}'''.<br/>
+
* {{Code|$key}} must not be empty.
{{Code|$algorithm}} describes the hash algorithm which is used for encryption. Currently supported are {{Code|md5}}, {{Code|sha1}}, {{Code|sha256}}, {{Code|sha384}}, {{Code|sha512}}. '''Default is {{Code|md5}}'''.
+
* {{Code|$algorithm}} describes the hash algorithm which is used for encryption. Currently supported are {{Code|md5}}, {{Code|sha1}}, {{Code|sha256}}, {{Code|sha384}}, {{Code|sha512}}. Default is {{Code|md5}}.
 +
* {{Code|$encoding}} must either be {{Code|hex}} or {{Code|base64}}; it specifies the encoding of the returned authentication code. Default is {{Code|base64}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|CX0013|XQuery Errors#Cryptographic Functions Errors}} the specified hashing algorithm is not supported.<br/>{{Error|CX0014|XQuery Errors#Cryptographic Functions Errors}} the specified encoding method is not supported.<br/>{{Error|CX0019|XQuery Errors#Cryptographic Functions Errors}} the specified secret key is invalid.<br/>
+
|{{Error|CX0013|#Errors}} the specified hashing algorithm is not supported.<br/>{{Error|CX0014|#Errors}} the specified encoding method is not supported.<br/>{{Error|CX0019|#Errors}} the specified secret key is invalid.<br/>
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|'''Returns the message authentication code (MAC) for a given string.'''
+
|Return message authentication code (MAC) for a given string:
 
 
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
crypto:hmac('message','secretkey','md5','base64')
+
crypto:hmac('message', 'secretkey', 'md5', 'hex')
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
34D1E3818B347252A75A4F6D747B21C2
 
34D1E3818B347252A75A4F6D747B21C2
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
 
=Encryption & Decryption=
 
=Encryption & Decryption=
 +
 
The encryption and decryption functions underlie several limitations:
 
The encryption and decryption functions underlie several limitations:
* Cryptographic algorithms are currently limited to {{Code|symmetric}} algorithms only. This means that the same secret key is used for encryption and decryption.  
+
* Cryptographic algorithms are currently limited to {{Code|symmetric}} algorithms. This means that the same secret key is used for encryption and decryption.
 
* Available algorithms are {{Code|DES}} and {{Code|AES}}.
 
* Available algorithms are {{Code|DES}} and {{Code|AES}}.
 
* Padding is fixed to {{Code|PKCS5Padding}}.
 
* Padding is fixed to {{Code|PKCS5Padding}}.
Line 46: Line 48:
  
 
==crypto:encrypt==
 
==crypto:encrypt==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|crypto:encrypt|$input as xs:string, $encryption as xs:string, $key as xs:string, $algorithm as xs:string|xs:string}}
+
|{{Func|crypto:encrypt|$data as xs:anyAtomicType, $type as xs:string, $key as xs:anyAtomicType, $algorithm as xs:string|xs:base64Binary}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Encrypts the given input string.<br/>
+
|Encrypts data with the specified key:
{{Code|$encryption}} must be {{Code|symmetric}}, as asymmetric encryption is not supported so far. '''Default is {{Code|symmetric}}'''.<br/>
+
* {{Code|$data}} must be a string or binary item.
{{Code|$key}} is the secret key which is used for both encryption and decryption of input data. Its length is fixed and depends on the chosen algorithm: {{Code|8 bytes for DES}}, {{Code|16 bytes for AES}}.<br/>
+
* {{Code|$type}} must be {{Code|symmetric}}.
{{Code|$algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. '''Default is {{Code|DES}}'''.
+
* {{Code|$key}} is the secret key which is used for both encryption and decryption of input data. It must be a string or binary item. Its length is fixed and depends on the chosen algorithm: 8 bytes for {{Code|DES}}, 16 bytes for {{Code|AES}}.
 +
* {{Code|$algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Default is {{Code|DES}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|CX0016|XQuery Errors#Cryptographic Functions Errors}} padding problems arise.<br/>{{Error|CX0017|XQuery Errors#Cryptographic Functions Errors}} padding is incorrect.<br/>{{Error|CX0018|XQuery Errors#Cryptographic Functions Errors}} the encryption type is not supported.<br/>{{Error|CX0019|XQuery Errors#Cryptographic Functions Errors}} the secret key is invalid.<br/>{{Error|CX0020|XQuery Errors#Cryptographic Functions Errors}} the block size is incorrect.<br/>{{Error|CX0021|XQuery Errors#Cryptographic Functions Errors}} the specified encryption algorithm is not supported.<br/>
+
|{{Error|CX0016|#Errors}} padding problems arise.<br/>{{Error|CX0017|#Errors}} padding is incorrect.<br/>{{Error|CX0018|#Errors}} the encryption type is not supported.<br/>{{Error|CX0019|#Errors}} the secret key is invalid.<br/>{{Error|CX0020|#Errors}} the block size is incorrect.<br/>{{Error|CX0021|#Errors}} the specified encryption algorithm is not supported.<br/>
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|'''Encrypts input data.'''
+
|Encrypt input data:
 
+
<syntaxhighlight lang="xquery">
'''Query:'''
+
crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')
<pre class="brush:xquery">
+
</syntaxhighlight>
crypto:encrypt('message', 'symmetric','keykeyke','DES')
 
</pre>
 
 
|}
 
|}
  
 
==crypto:decrypt==
 
==crypto:decrypt==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|crypto:decrypt|$input as xs:string, $type as xs:string, $key as xs:string, $algorithm as xs:string|xs:string}}
+
|{{Func|crypto:decrypt|$data as xs:anyAtomicType, $type as xs:string, $key as xs:anyAtomicType, $algorithm as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Decrypts the encrypted {{Code|$input}}.<br/>
+
|Encrypts data with the specified key:
{{Code|$type}} must be {{Code|symmetric}}. An option for asymmetric encryption will most likely be added with another version of BaseX. '''Default is {{Code|symmetric}}'''.<br/>
+
* {{Code|$data}} must be a string or binary item.
{{Code|$key}} is the secret key which is used for both encryption and decryption of input data. Its length is fixed and depends on the chosen algorithm: {{Code|8 bytes for DES}}, {{Code|16 bytes for AES}}.<br/>
+
* {{Code|$type}} must be {{Code|symmetric}}.
{{Code|$algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. '''Default is {{Code|DES}}'''.
+
* {{Code|$key}} is the secret key which is used for both encryption and decryption of input data. It must be a string or binary item. Its length is fixed and depends on the chosen algorithm: 8 bytes for {{Code|DES}}, 16 bytes for {{Code|AES}}.
 +
* {{Code|$algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Default is {{Code|DES}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|CX0016|XQuery Errors#Cryptographic Functions Errors}} padding problems arise.<br/>{{Error|CX0017|XQuery Errors#Cryptographic Functions Errors}} padding is incorrect.<br/>{{Error|CX0018|XQuery Errors#Cryptographic Functions Errors}} the encryption type is not supported.<br/>{{Error|CX0019|XQuery Errors#Cryptographic Functions Errors}} the secret key is invalid.<br/>{{Error|CX0020|XQuery Errors#Cryptographic Functions Errors}} the block size is incorrect.<br/>{{Error|CX0021|XQuery Errors#Cryptographic Functions Errors}} the specified encryption algorithm is not supported.<br/>
+
|{{Error|CX0016|#Errors}} padding problems arise.<br/>{{Error|CX0017|#Errors}} padding is incorrect.<br/>{{Error|CX0018|#Errors}} the encryption type is not supported.<br/>{{Error|CX0019|#Errors}} the secret key is invalid.<br/>{{Error|CX0020|#Errors}} the block size is incorrect.<br/>{{Error|CX0021|#Errors}} the specified encryption algorithm is not supported.<br/>
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|'''Decrypts input data and returns the original string.'''
+
|Decrypt input data and return original string:
 
 
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
let $encrypted := crypto:encrypt('message', 'symmetric','keykeyke','DES')
+
let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')
return crypto:decrypt($encrypted, 'symmetric','keykeyke','DES')
+
return crypto:decrypt($encrypted, 'symmetric', 'keykeyke', 'DES')
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
message
 
message
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
 
=XML Signatures=
 
=XML Signatures=
[http://www.w3.org/TR/xmldsig-core/ XML Signatures] are used to sign data. In our case, the data which is signed is an XQuery node. The following example shows the basic structure of an XML signature.
+
 
 +
[https://www.w3.org/TR/xmldsig-core/ XML Signatures] are used to sign data. In our case, the data which is signed is an XQuery node. The following example shows the basic structure of an XML signature.
  
 
'''XML Signature'''
 
'''XML Signature'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<Signature>
 
<Signature>
 
   <SignedInfo>
 
   <SignedInfo>
Line 119: Line 123:
 
   <Object/>
 
   <Object/>
 
</Signature>
 
</Signature>
</pre>
+
</syntaxhighlight>
  
 
* '''SignedInfo''' contains or references the signed data and lists algorithm information
 
* '''SignedInfo''' contains or references the signed data and lists algorithm information
Line 137: Line 141:
 
The {{Code|generate-signature}} function allows to pass a {{Code|digital certificate}}. This certificate holds parameters that allow to access key information stored in a Java key store which is then used to sign the input document. Passing a {{Code|digital certificate}} simply helps re-using the same key pair to sign and validate data. The {{Code|digital certificate}} is passed as a node and has the following form:
 
The {{Code|generate-signature}} function allows to pass a {{Code|digital certificate}}. This certificate holds parameters that allow to access key information stored in a Java key store which is then used to sign the input document. Passing a {{Code|digital certificate}} simply helps re-using the same key pair to sign and validate data. The {{Code|digital certificate}} is passed as a node and has the following form:
  
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<digital-certificate>
 
<digital-certificate>
 
   <keystore-type>JKS</keystore-type>
 
   <keystore-type>JKS</keystore-type>
Line 145: Line 149:
 
   <keystore-uri>...</keystore-uri>
 
   <keystore-uri>...</keystore-uri>
 
</digital-certificate>
 
</digital-certificate>
</pre>
+
</syntaxhighlight>
  
 
==crypto:generate-signature==
 
==crypto:generate-signature==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string|node()}}<br/>{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $ext as item()|node()}}<br/>{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $xpath as xs:string, $certificate as node()|node()}}
+
|{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string|node()}}<br/>{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $xpath as xs:string, $certificate as node()|node()}}<br/>{{Func|crypto:generate-signature|$input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $ext as item()|node()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 160: Line 165:
 
{{Code|$type}} is the signature type. It must either be {{Code|enveloped}} or {{Code|enveloping}} (detached signatures are not supported so far). '''Default is {{Code|enveloped}}'''.<br/>
 
{{Code|$type}} is the signature type. It must either be {{Code|enveloped}} or {{Code|enveloping}} (detached signatures are not supported so far). '''Default is {{Code|enveloped}}'''.<br/>
 
{{Code|$xpath}} is an arbitrary XPath expression which specifies a subset of the document that is to be signed.<br/>
 
{{Code|$xpath}} is an arbitrary XPath expression which specifies a subset of the document that is to be signed.<br/>
{{Code|$certificate}} is the digitial certificate used to sign the input document.
+
{{Code|$certificate}} is the digitial certificate used to sign the input document.<br/>
 
{{Code|$ext}} may either be an {{Code|$xpath}} expression or a {{Code|$certificate}}.<br/>
 
{{Code|$ext}} may either be an {{Code|$xpath}} expression or a {{Code|$certificate}}.<br/>
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|CX0001|XQuery Errors#Cryptographic Functions Errors}} the canonicalization algorithm is not supported.<br/>{{Error|CX0002|XQuery Errors#Cryptographic Functions Errors}} the digest algorithm is not supported.<br/>{{Error|CX0003|XQuery Errors#Cryptographic Functions Errors}} the signature algorithm is not supported.<br/>{{Error|CX0004|XQuery Errors#Cryptographic Functions Errors}} the {{Code|$xpath-expression}} is invalid.<br/>{{Error|CX0005|XQuery Errors#Cryptographic Functions Errors}} the root name of {{Code|$digital-certificate}} is not 'digital-certificate.<br/>{{Error|CX0007|XQuery Errors#Cryptographic Functions Errors}} the key store is null.<br/>{{Error|CX0012|XQuery Errors#Cryptographic Functions Errors}} the key cannot be found in the specified key store.<br/>{{Error|CX0023|XQuery Errors#Cryptographic Functions Errors}} the certificate alias is invalid.<br/>{{Error|CX0024|XQuery Errors#Cryptographic Functions Errors}} an invalid algorithm is specified.<br/>{{Error|CX0025|XQuery Errors#Cryptographic Functions Errors}} an exception occurs while the signing the document.<br/>{{Error|CX0026|XQuery Errors#Cryptographic Functions Errors}} an exception occurs during key store initialization.<br/>{{Error|CX0027|XQuery Errors#Cryptographic Functions Errors}} an IO exception occurs.<br/>{{Error|CX0028|XQuery Errors#Cryptographic Functions Errors}} the signature type is not supported.<br/>
+
|{{Error|CX0001|#Errors}} the canonicalization algorithm is not supported.<br/>{{Error|CX0002|#Errors}} the digest algorithm is not supported.<br/>{{Error|CX0003|#Errors}} the signature algorithm is not supported.<br/>{{Error|CX0004|#Errors}} the {{Code|$xpath-expression}} is invalid.<br/>{{Error|CX0005|#Errors}} the root name of {{Code|$digital-certificate}} is not 'digital-certificate.<br/>{{Error|CX0007|#Errors}} the key store is null.<br/>{{Error|CX0012|#Errors}} the key cannot be found in the specified key store.<br/>{{Error|CX0023|#Errors}} the certificate alias is invalid.<br/>{{Error|CX0024|#Errors}} an invalid algorithm is specified.<br/>{{Error|CX0025|#Errors}} an exception occurs while the signing the document.<br/>{{Error|CX0026|#Errors}} an exception occurs during key store initialization.<br/>{{Error|CX0027|#Errors}} an IO exception occurs.<br/>{{Error|CX0028|#Errors}} the signature type is not supported.<br/>
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|'''Generates an [http://www.w3.org/TR/xmldsig-core/ XML Signature].'''
+
|Generate [https://www.w3.org/TR/xmldsig-core/ XML Signature]:
  
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
crypto:generate-signature(<a/>, '', '', '', '', '')
 
crypto:generate-signature(<a/>, '', '', '', '', '')
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
<a>
 
<a>
 
   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
 
   <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
Line 202: Line 207:
 
   </Signature>
 
   </Signature>
 
</a>
 
</a>
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
 
==crypto:validate-signature==
 
==crypto:validate-signature==
 +
 
{| width='100%'
 
{| width='100%'
 
|-
 
|-
Line 215: Line 221:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|CX0015|XQuery Errors#Cryptographic Functions Errors}} the signature element cannot be found.<br/>{{Error|CX9994|XQuery Errors#Cryptographic Functions Errors}} an unspecified problem occurs during validation.<br/>{{Error|CX9996|XQuery Errors#Cryptographic Functions Errors}} an IO exception occurs during validation.<br/>
+
|{{Error|CX0015|#Errors}} the signature element cannot be found.<br/>{{Error|CX9994|#Errors}} an unspecified problem occurs during validation.<br/>{{Error|CX9996|#Errors}} an IO exception occurs during validation.<br/>
 
|-
 
|-
 
| '''Example'''
 
| '''Example'''
|'''Validates an [http://www.w3.org/TR/xmldsig-core/ XML Signature].'''
+
|Validate [https://www.w3.org/TR/xmldsig-core/ XML Signature]:
  
 
'''Query:'''
 
'''Query:'''
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')
 
let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')
 
return crypto:validate-signature($sig)
 
return crypto:validate-signature($sig)
</pre>
+
</syntaxhighlight>
  
 
'''Result:'''
 
'''Result:'''
<pre class="brush:xml">
+
<syntaxhighlight lang="xml">
 
true
 
true
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 321: Line 327:
  
 
=Changelog=
 
=Changelog=
 +
 +
;Version 9.3
 +
* Updated: [[#crypto:hmac|crypto:hmac]], [[#crypto:encrypt|crypto:encrypt]], [[#crypto:decrypt|crypto:decrypt]]: Function types revised.
 +
 +
;Version 8.6
 +
* Updated: [[#crypto:hmac|crypto:hmac]]: The key can now be a string or a binary item.
  
 
The Module was introduced with Version 7.0.
 
The Module was introduced with Version 7.0.
 
[[Category:XQuery]]
 

Revision as of 11:50, 8 July 2020

This XQuery Module contains functions to perform cryptographic operations in XQuery. The cryptographic module is based on an early draft of the EXPath Cryptographic Module and provides the following functionality: creation of message authentication codes (HMAC), encryption and decryption, and creation and validation of XML Digital Signatures.

Conventions

All functions in this module are assigned to the http://expath.org/ns/crypto namespace, which is statically bound to the crypto prefix.
All errors are assigned to the http://expath.org/ns/error namespace, which is statically bound to the experr prefix.

Message Authentication

crypto:hmac

Signatures crypto:hmac($data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string) as xs:string
crypto:hmac($data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string, $encoding as xs:string) as xs:string
Summary Creates an authentication code for the specified $data via a cryptographic hash function:
  • $key must not be empty.
  • $algorithm describes the hash algorithm which is used for encryption. Currently supported are md5, sha1, sha256, sha384, sha512. Default is md5.
  • $encoding must either be hex or base64; it specifies the encoding of the returned authentication code. Default is base64.
Errors CX0013: the specified hashing algorithm is not supported.
CX0014: the specified encoding method is not supported.
CX0019: the specified secret key is invalid.
Example Return message authentication code (MAC) for a given string:

Query: <syntaxhighlight lang="xquery"> crypto:hmac('message', 'secretkey', 'md5', 'hex') </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> 34D1E3818B347252A75A4F6D747B21C2 </syntaxhighlight>

Encryption & Decryption

The encryption and decryption functions underlie several limitations:

  • Cryptographic algorithms are currently limited to symmetric algorithms. This means that the same secret key is used for encryption and decryption.
  • Available algorithms are DES and AES.
  • Padding is fixed to PKCS5Padding.
  • The result of an encryption using the same message, algorithm and key looks different each time it is executed. This is due to a random initialization vector (IV) which is appended to the message and simply increases security.
  • As the IV has to be passed along with the encrypted message somehow, data which has been encrypted by the crypto:encrypt function in BaseX can only be decrypted by calling the crypto:decrypt function.

crypto:encrypt

Signatures crypto:encrypt($data as xs:anyAtomicType, $type as xs:string, $key as xs:anyAtomicType, $algorithm as xs:string) as xs:base64Binary
Summary Encrypts data with the specified key:
  • $data must be a string or binary item.
  • $type must be symmetric.
  • $key is the secret key which is used for both encryption and decryption of input data. It must be a string or binary item. Its length is fixed and depends on the chosen algorithm: 8 bytes for DES, 16 bytes for AES.
  • $algorithm must either be DES or AES. Default is DES.
Errors CX0016: padding problems arise.
CX0017: padding is incorrect.
CX0018: the encryption type is not supported.
CX0019: the secret key is invalid.
CX0020: the block size is incorrect.
CX0021: the specified encryption algorithm is not supported.
Example Encrypt input data:

<syntaxhighlight lang="xquery"> crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES') </syntaxhighlight>

crypto:decrypt

Signatures crypto:decrypt($data as xs:anyAtomicType, $type as xs:string, $key as xs:anyAtomicType, $algorithm as xs:string) as xs:string
Summary Encrypts data with the specified key:
  • $data must be a string or binary item.
  • $type must be symmetric.
  • $key is the secret key which is used for both encryption and decryption of input data. It must be a string or binary item. Its length is fixed and depends on the chosen algorithm: 8 bytes for DES, 16 bytes for AES.
  • $algorithm must either be DES or AES. Default is DES.
Errors CX0016: padding problems arise.
CX0017: padding is incorrect.
CX0018: the encryption type is not supported.
CX0019: the secret key is invalid.
CX0020: the block size is incorrect.
CX0021: the specified encryption algorithm is not supported.
Example Decrypt input data and return original string:

Query: <syntaxhighlight lang="xquery"> let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES') return crypto:decrypt($encrypted, 'symmetric', 'keykeyke', 'DES') </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> message </syntaxhighlight>

XML Signatures

XML Signatures are used to sign data. In our case, the data which is signed is an XQuery node. The following example shows the basic structure of an XML signature.

XML Signature <syntaxhighlight lang="xml"> <Signature>

 <SignedInfo>
   <CanonicalizationMethod/>
   <SignatureMethod/>
   <Reference>
     <Transforms/>
     <DigestMethod/>
     <DigestValue/>
   </Reference>
   <Reference/>
 </SignedInfo>
 <SignatureValue/>
 <KeyInfo/>
 <Object/>

</Signature> </syntaxhighlight>

  • SignedInfo contains or references the signed data and lists algorithm information
  • Reference references the signed node
  • Transforms contains transformations (i.e. XPath expressions) that are applied to the input node in order to sign a subset
  • DigestValue holds digest value of the transformed references
  • SignatureValue contains the Base64 encoded value of the encrypted digest of the SignedInfo element
  • KeyInfo provides information on the key that is used to validate the signature
  • Object contains the node which is signed if the signature is of type enveloping

Signature Types

Depending on the signature type, the signature element is either placed as a child of the signed node (enveloped type), or directly contains the signed node (enveloping type). Detached signatures are so far not supported.

Digital Certificate

The generate-signature function allows to pass a digital certificate. This certificate holds parameters that allow to access key information stored in a Java key store which is then used to sign the input document. Passing a digital certificate simply helps re-using the same key pair to sign and validate data. The digital certificate is passed as a node and has the following form:

<syntaxhighlight lang="xml"> <digital-certificate>

 <keystore-type>JKS</keystore-type>
 <keystore-password>...</keystore-password>
 <key-alias>...</key-alias>
 <private-key-password>...</private-key-password>
 <keystore-uri>...</keystore-uri>

</digital-certificate> </syntaxhighlight>

crypto:generate-signature

Signatures crypto:generate-signature($input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string) as node()
crypto:generate-signature($input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $xpath as xs:string, $certificate as node()) as node()
crypto:generate-signature($input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $ext as item()) as node()
Summary $canonicalization must either be inclusive-with-comments, inclusive, exclusive-with-comments or exclusive. Default is inclusive-with-comments.

$digest must be one of the following: SHA1, SHA256 or SHA512. Default is SHA1.
$signature must either be RSA_SHA1 or DSA_SHA1. Default is RSA_SHA1.
$prefix may be empty and prefixes the Signature element accordingly.
$type is the signature type. It must either be enveloped or enveloping (detached signatures are not supported so far). Default is enveloped.
$xpath is an arbitrary XPath expression which specifies a subset of the document that is to be signed.
$certificate is the digitial certificate used to sign the input document.
$ext may either be an $xpath expression or a $certificate.

Errors CX0001: the canonicalization algorithm is not supported.
CX0002: the digest algorithm is not supported.
CX0003: the signature algorithm is not supported.
CX0004: the $xpath-expression is invalid.
CX0005: the root name of $digital-certificate is not 'digital-certificate.
CX0007: the key store is null.
CX0012: the key cannot be found in the specified key store.
CX0023: the certificate alias is invalid.
CX0024: an invalid algorithm is specified.
CX0025: an exception occurs while the signing the document.
CX0026: an exception occurs during key store initialization.
CX0027: an IO exception occurs.
CX0028: the signature type is not supported.
Example Generate XML Signature:

Query: <syntaxhighlight lang="xquery"> crypto:generate-signature(<a/>, , , , , ) </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> <a>

 <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
   <SignedInfo>
     <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
     <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
     <Reference URI="">
       <Transforms>
         <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
       </Transforms>
       <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
       <DigestValue>9hvH4qztnIYgYfJDRLnEMPJdoaY=</DigestValue>
     </Reference>
   </SignedInfo>
   <SignatureValue>Pn/Jr44WBcdARff2UVYEiwYW1563XdqnU87nusAIaHgzd+U3SrjVJhPFLDe0DJfxVtYzLFaznTYE

P3ddeoFmyA==</SignatureValue>

   <KeyInfo>
     <KeyValue>
       <RSAKeyValue>
         <Modulus>rtvpFSbCIE2BJePlVYLIRIjXl0R7ESr2+D+JOVKn7AM7VZbcbRDPeqRbjSkEz1HWC/N067tjB3qH

4/4PPT9bGQ==</Modulus>

         <Exponent>AQAB</Exponent>
       </RSAKeyValue>
     </KeyValue>
   </KeyInfo>
 </Signature>

</a> </syntaxhighlight>

crypto:validate-signature

Signatures crypto:validate-signature($input-doc as node()) as xs:boolean
Summary Checks if the given node contains a Signature element and whether the signature is valid. In this case true is returned. If the signature is invalid the function returns false.
Errors CX0015: the signature element cannot be found.
CX9994: an unspecified problem occurs during validation.
CX9996: an IO exception occurs during validation.
Example Validate XML Signature:

Query: <syntaxhighlight lang="xquery"> let $sig := crypto:generate-signature(<a/>, , , , , ) return crypto:validate-signature($sig) </syntaxhighlight>

Result: <syntaxhighlight lang="xml"> true </syntaxhighlight>

Errors

Code Description
CX0001 The canonicalization algorithm is not supported.
CX0002 The digest algorithm is not supported.
CX0003 The signature algorithm is not supported.
CX0004 The XPath expression is invalid.
CX0005 The root element of argument $digital-certificate must have the name 'digital-certificate'.
CX0006 The child element of argument $digital-certificate having position $position must have the name $child-element-name.
CX0007 The keystore is null.
CX0008 I/O error while reading keystore.
CX0009 Permission denied to read keystore.
CX0010 The keystore URL is invalid.
CX0011 The keystore type is not supported.
CX0012 Cannot find key for alias in given keystore.
CX0013 The hashing algorithm is not supported.
CX0014 The encoding method is not supported.
CX0015 Cannot find Signature element.
CX0016 No such padding.
CX0017 Incorrect padding.
CX0018 The encryption type is not supported.
CX0019 The secret key is invalid.
CX0020 Illegal block size.
CX0021 The algorithm is not supported.
CX0023 An invalid certificate alias is specified. Added to the official specification.
CX0024 The algorithm is invalid. Added to the official specification.
CX0025 Signature cannot be processed. Added to the official specification.
CX0026 Keystore cannot be processed. Added to the official specification.
CX0027 An I/O Exception occurred. Added to the official specification.
CX0028 The specified signature type is not supported. Added to the official specification.

Changelog

Version 9.3
Version 8.6
  • Updated: crypto:hmac: The key can now be a string or a binary item.

The Module was introduced with Version 7.0.