Changes

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 /20110810 EXPath Cryptographic Module] and provides the following functionality:# Creation creation of message authentication codes (HMAC)# Creation , encryption and decryption, and creation and validation of an XML Digital SignatureSignatures. =Conventions= # Encryption and decryptionAll 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><nowiki>http://expath.org/ns/error</nowiki></code> namespace, which is statically bound to the {{Code|experr}} prefix. =Message Authentication=

 {|width='100%'|-| valign='"top' "| width='90120' | '''SignaturesSignature'''|<code><bpre>crypto:hmac</b>( $message data as xs:string()anyAtomicType, $secret-key as xs:anyAtomicType, $algorithm as xs:string(), algorithm $encoding as xs:string := ()) as xs:string()</pre>|- valign="top"| '''Summary'''|Creates an authentication code for the specified {{Code|$data}} via a cryptographic hash function:* {{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|$encoding}} must either be {{Code|hex}} or {{Code|base64}}; it specifies the encoding of the returned authentication code. Default is {{Code|base64}}.|- valign="top"| '''Errors'''|{{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/>|- valign="top"| '''Example'''|Return message authentication code>(MAC) for a given string:'''Query:'''<bpre lang='xquery'>crypto:hmac('message', 'secretkey', 'md5', 'hex')</bpre> '''Result:'''<pre lang="xml">34D1E3818B347252A75A4F6D747B21C2</pre>|} =Encryption & Decryption= The encryption and decryption functions underlie several limitations:* 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}}.* Padding is fixed to {{Code|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 {{Code|crypto:encrypt}} function in BaseX can only be decrypted by calling the {{Code|crypto:decrypt}} function. ==crypto:encrypt== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>crypto:encrypt( $message data as xs:anyAtomicType, $type as xs:string(), $secret-key as xs:anyAtomicType, $algorithm as xs:string) as xs:base64Binary</pre>|- valign="top"| '''Summary'''|Encrypts data with the specified key:* {{Code|$data}} must be a string or binary item.* {{Code|$type}} must be {{Code|symmetric}}.* {{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}}.|- valign="top"| '''Errors'''|{{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/>|- valign="top"| '''Example'''|Encrypt input data:<pre lang='xquery'>crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')</pre>|} ==crypto:decrypt== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>crypto:decrypt( $data as xs:anyAtomicType, algorithm $type as xs:string(), $key as xs:anyAtomicType, $encoding algorithm as xs:string()) as xs:string()</codepre>|-valign="top"| '''Summary'''|Encrypts data with the specified key:* {{Code|$data}} must be a string or binary item.* {{Code|$type}} must be {{Code|symmetric}}.* {{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}}.|- valign="top"| '''Errors'''|{{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/>|- valign="top"| '''Example' ''| Decrypt input data and return original string:'''Query:''Summary'<pre lang='xquery'>let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')return crypto:decrypt($encrypted, 'symmetric', 'keykeyke', 'DES')</pre> '''Result:'''<pre lang="xml">message</pre>|Creates } =XML Signatures= [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'''<pre lang="xml"><Signature> <SignedInfo> <CanonicalizationMethod/> <SignatureMethod/> <Reference> <Transforms/> <DigestMethod/> <DigestValue/> </Reference> <Reference/> </SignedInfo> <SignatureValue/> <KeyInfo/> <Object/></Signature></pre> * '''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 message authentication code via subset * '''DigestValue''' holds digest value of the transformed references* '''SignatureValue''' contains the Base64 encoded value of the encrypted digest of the {{Code|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 {{Code|enveloping}} '''Signature Types''' Depending on the signature type, the {{Code|signature}} element is either placed as a cryptographic hash child of the signed node ({{Code|enveloped}} type), or directly contains the signed node ({{Code|enveloping}} type). {{Code|Detached}} signatures are so far not supported. '''Digital Certificate''' 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 secret node and has the following form: <pre 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>... <br/keystore-uri></digital-certificate></pre> ==crypto:generate-signature== {| width='100%'|- valign="top"| width='120' | '''Signature'''|<pre>crypto:generate-signature( $encoding input as node(), $canonicalization as xs:string, $digest as xs:string, $signature as xs:string, $prefix as xs:string, $type as xs:string, $ext1 as item(), $ext2 as node()) as node()</pre>|- valign="top"| '''Summary'''|{{Code|$canonicalization}} must either be {{Code|inclusive-with-comments}}, {{Code|inclusive}}, {{Code|exclusive-with-comments}} or {{Code|exclusive}}. '''Default is {{Code|inclusive-with-comments}}'''.<codebr/>hex{{Code|$digest}} must be one of the following: {{Code|SHA1}}, {{Code|SHA256}} or {{Code|SHA512}}. '''Default is {{Code|SHA1}}'''.<br/code>, {{Code|$signature}} must either be {{Code|RSA_SHA1}} or {{Code|DSA_SHA1}}. '''Default is {{Code|RSA_SHA1}}'''.<codebr/>base64{{Code|$prefix}} may be empty and prefixes the {{Code|Signature}} element accordingly.<br/code> {{Code|$type}} is the signature type. It must either be {{Code|enveloped}} or the empty string {{Code|enveloping}} (default detached signatures are not supported so far). '''Default is {{Code|enveloped}}'''.<codebr/>base64{{Code|$ext1}} may either be an {{Code|$xpath}} expression or a {{Code|$certificate}}.<br/code>) If {{Code|$ext2}} is specified as well, {{Code|$ext1}} is an arbitrary XPath expression which specifies a subset of the document that is to be signed, and specifies {{Code|$ext2}} is the encoding of digitial certificate used to sign the returned authentication codeinput document.<br/>|-valign="top"| '''Errors'''|{{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/>| - valign="top"| '''Example''top' | Generate [https://www.w3.org/TR/xmldsig-core/ XML Signature]: '''Query:'''<pre lang='xquery'>crypto:generate-signature(<a/>, '', '', '', 'Errors', '')</pre> '''Result:'''|<bpre 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+U3SrjVJhPFLDe0DJfxVtYzLFaznTYEP3ddeoFmyA==</SignatureValue> <KeyInfo> <KeyValue> <RSAKeyValue> <Modulus>rtvpFSbCIE2BJePlVYLIRIjXl0R7ESr2+D+JOVKn7AM7VZbcbRDPeqRbjSkEz1HWC/N067tjB3qH4/4PPT9bGQ==</Modulus> <Exponent>AQAB</Exponent> </RSAKeyValue> </KeyValue> </KeyInfo> </Signature></a>?</bpre>