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

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|crypto:hmac|$message as xs:string, $key as xs:string, $algorithm as xs:string|xs:string}}<br/pre>{{Func|crypto:hmac|( $message data as xs:stringanyAtomicType, $key as xs:stringanyAtomicType, $algorithm as xs:string, $encoding as xs:string| := ()) as xs:string}}</pre>|-valign="top"

|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}}.|-valign="top"

|{{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/>|-valign="top"

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

<pre classlang="brush:'xquery"'>crypto:hmac('message','secretkey','md5','base64hex')

<pre classlang="brush:xml">

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

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>crypto:encrypt|( $input data as xs:stringanyAtomicType, $encryption type as xs:string, $key as xs:stringanyAtomicType, $algorithm as xs:string|) as xs:string}}base64Binary</pre>|-valign="top"

|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}}'''.|-valign="top"

|{{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/>|-valign="top"

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

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>crypto:decrypt|( $input data as xs:stringanyAtomicType, $type as xs:string, $key as xs:stringanyAtomicType, $algorithm as xs:string|) as xs:string}}</pre>|-valign="top"

|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}}'''.|-valign="top"

|{{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/>|-valign="top"

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

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

<pre classlang="brush:xml">

 [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 classlang="brush:xml">

<pre classlang="brush:xml">

|-valign="top"| width='120' | '''SignaturesSignature'''|{{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/pre>{{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 ext1 as xs:stringitem(), $certificate ext2 as node()|) as node()}}<br/pre>{{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()}}|-valign="top"

{{Code|$ext1}} may either be an {{Code|$xpath}} is an arbitrary XPath expression which specifies or a subset of the document that is to be signed.<br/>{{Code|$certificate}} is the digitial certificate used to sign the input document.<br/>If {{Code|$extext2}} may either be an is specified as well, {{Code|$xpathext1}} is an arbitrary XPath expression or which specifies a subset of the document that is to be signed, and {{Code|$certificateext2}}is the digitial certificate used to sign the input document.<br/>|-valign="top"

|{{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/>|-valign="top"

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

<pre classlang="brush:'xquery"'>

<pre classlang="brush:xml">

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|<pre>crypto:validate-signature|( $input-doc as node()|) as xs:boolean}}</pre>|-valign="top"

|-valign="top"

|{{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/>|-| '''Example'''|'''Validates an [http://www.w3.org/TR/xmldsig-core/ XML Signature].''' '''Query:'''<pre class="brush:xquery">let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')return crypto:validate-signature($sig)</pre> '''Result:'''<pre class="brush:xml">true</pre>

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"

|-valign="top"