Changes

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.

All functions in this module are assigned to the {{Code|<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|<code><nowiki>http://expath.org/ns/error}} </nowiki></code> namespace, which is statically bound to the {{Code|experr}} prefix.

|{{Func|crypto:hmac|$message data as xs:stringanyAtomicType, $key as xs:stringanyAtomicType, $algorithm as xs:string|xs:string}}<br/>{{Func|crypto:hmac|$message data as xs:stringanyAtomicType, $key as xs:stringanyAtomicType, $algorithm as xs:string, $encoding as xs:string|xs:string}}

|Creates a message an authentication code via a cryptographic hash function and a secret for the specified {{Code|$keydata}}. <br/>via a cryptographic hash function:* {{Code|$encodingkey}} must either not be {{Code|hex}}, {{Code|base64}} or the empty string and specifies the encoding of the returned authentication code. '''Default is {{Code|base64}}'''.<br/>* {{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}}.

|{{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/>

|'''Returns the Return message authentication code (MAC) for a given string.''':

<pre classsyntaxhighlight lang="brush:xquery">crypto:hmac('message','secretkey','md5','base64hex')</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

* Cryptographic algorithms are currently limited to {{Code|symmetric}} algorithms only. This means that the same secret key is used for encryption and decryption.

|{{Func|crypto:encrypt|$input data as xs:stringanyAtomicType, $encryption type as xs:string, $key as xs:stringanyAtomicType, $algorithm as xs:string|xs:stringbase64Binary}}

|Encrypts data with the given input string.<br/>specified key:* {{Code|$encryptiondata}} must be a string or binary item.* {{Code|symmetric$type}}, as asymmetric encryption is not supported so far. '''Default is must be {{Code|symmetric}}'''.<br/>* {{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|8 bytes for DES}}, 16 bytes for {{Code|16 bytes for AES}}.<br/>* {{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}}'''.

|{{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/>

|'''Encrypts Encrypt input data.''' '''Query:'''<pre classsyntaxhighlight lang="brush:xquery">crypto:encrypt('message', 'symmetric','keykeyke','DES')</presyntaxhighlight>

|{{Func|crypto:decrypt|$input data as xs:stringanyAtomicType, $type as xs:string, $key as xs:stringanyAtomicType, $algorithm as xs:string|xs:string}}

|Decrypts Encrypts data with the encrypted specified key:* {{Code|$inputdata}}must be a string or binary item.<br/>* {{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|$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|8 bytes for DES}}, 16 bytes for {{Code|16 bytes for AES}}.<br/>* {{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}}'''.

|{{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/>

|'''Decrypts Decrypt input data and returns the return original string.''':

<pre classsyntaxhighlight lang="brush:xquery">let $encrypted := crypto:encrypt('message', 'symmetric','keykeyke','DES')return crypto:decrypt($encrypted, 'symmetric','keykeyke','DES')</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

 [httphttps://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.

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

|{{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 xpath as xs:string, $certificate as itemnode()|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 ext as xs:string, $certificate as nodeitem()|node()}}

{{Code|$certificate}} is the digitial certificate used to sign the input document.<br/>

|{{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/>

|'''Generates an Generate [httphttps://www.w3.org/TR/xmldsig-core/ XML Signature].''':

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

|{{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/>

|'''Validates an Validate [httphttps://www.w3.org/TR/xmldsig-core/ XML Signature].''':

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>