Difference between revisions of "Cryptographic Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "| valign='top' width='90' |" to "| width='90' |")
Line 4: Line 4:
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the <code>http://expath.org/ns/crypto</code> namespace, which is statically bound to the <code>crypto</code> prefix.<br/>
+
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 errors are assigned to the <code>http://expath.org/ns/error</code> namespace, which is statically bound to the <code>experr</code> prefix.
+
All errors are assigned to the {{Code|http://expath.org/ns/error}} namespace, which is statically bound to the {{Code|experr}} prefix.
  
 
=Message Authentication=
 
=Message Authentication=
Line 13: Line 13:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>crypto:hmac</b>($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string()) as xs:string()</code><br/><code><b>crypto:hmac</b>($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string(), $encoding as xs:string()) as xs:string()</code>
+
|{{Func|crypto:hmac|$message as xs:string(), $secret-key as xs:string(), algorithm as xs:string()|xs:string()}}<br/>{{Func|crypto:hmac|$message as xs:string(), $secret-key as xs:string(), 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 key. <br/>
 
|Creates a message authentication code via a cryptographic hash function and a secret key. <br/>
−
<code>$encoding</code> must either be <code>hex</code>, <code>base64</code> or the empty string and specifies the encoding of the returned authentication code. <b>Default is <code>base64</code></b>.<br/>
+
{{Code|$encoding}} must either be {{Code|hex}}, {{Code|base64}} or the empty string and specifies the encoding of the returned authentication code. <b>Default is {{Code|base64}}</b>.<br/>
−
<code>$algorithm</code> describes the hash algorithm which is used for encryption. Currently supported are <code>md5</code>, <code>sha1</code>, <code>sha256</code>, <code>sha384</code>, <code>sha512</code>. <b>Default is <code>md5</code></b>.
+
{{Code|$algorithm}} describes the hash algorithm which is used for encryption. Currently supported are {{Code|md5}}, {{Code|sha1}}, {{Code|sha256}}, {{Code|sha384}}, {{Code|sha512}}. <b>Default is {{Code|md5}}</b>.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 41: Line 41:
 
=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</code> algorithms only. This means that the same secret key is used for encryption and decryption.  
+
* Cryptographic algorithms are currently limited to {{Code|symmetric}} algorithms only. This means that the same secret key is used for encryption and decryption.  
−
* Available algorithms are <code>DES</code> and <code>AES</code>.
+
* Available algorithms are {{Code|DES}} and {{Code|AES}}.
−
* Padding is fixed to <code>PKCS5Padding</code>.
+
* 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.
 
* 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</code> function in BaseX can only be decrypted by calling the <code>crypto:decrypt</code> function.
+
* 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==
 
==crypto:encrypt==
Line 51: Line 51:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>crypto:encrypt</b>($input as xs:string(), $encryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()</code>
+
|{{Func|crypto:encrypt|$input as xs:string(), $encryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()|xs:string()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
 
|Encrypts the given input string.<br/>
 
|Encrypts the given input string.<br/>
−
<code>$encryption-type</code> must be <code>symmetric</code>, as asymmetric encryption is not supported so far. <b>Default is <code>symmetric</code></b>.<br/>
+
{{Code|$encryption-type}} must be {{Code|symmetric}}, as asymmetric encryption is not supported so far. <b>Default is {{Code|symmetric}}</b>.<br/>
−
<code>$secret-key</code> 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>, <code>16 bytes for AES</code>.<br/>
+
{{Code|$secret-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>$cryptographic-algorithm</code> must either be <code>DES</code> or <code>AES</code>. Other algorithms are not supported so far, but, of course, can be added on demand. <b>Default is <code>DES</code></b>.
+
{{Code|$cryptographic-algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. <b>Default is {{Code|DES}}</b>.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 80: Line 80:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>crypto:decrypt</b>($input as xs:string(), $decryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()</code>
+
|{{Func|crypto:decrypt|$input as xs:string(), $decryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()|xs:string()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Decrypts the encrypted <code>$input</code>.<br/>
+
|Decrypts the encrypted {{Code|$input}}.<br/>
−
<code>$decryption-type</code> must be <code>symmetric</code>. An option for asymmetric encryption will most likely be added with another version of BaseX. <b>Default is <code>symmetric</code></b>.<br/>
+
{{Code|$decryption-type}} must be {{Code|symmetric}}. An option for asymmetric encryption will most likely be added with another version of BaseX. <b>Default is {{Code|symmetric}}</b>.<br/>
−
<code>$secret-key</code> 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>, <code>16 bytes for AES</code>.<br/>
+
{{Code|$secret-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>$cryptographic-algorithm</code> must either be <code>DES</code> or <code>AES</code>. Other algorithms are not supported so far, but, of course, can be added on demand. <b>Default is <code>DES</code></b>.
+
{{Code|$cryptographic-algorithm}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. <b>Default is {{Code|DES}}</b>.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 137: Line 137:
 
* '''Transforms''' contains transformations (i.e. XPath expressions) that are applied to the input node in order to sign a subset  
 
* '''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
 
* '''DigestValue''' holds digest value of the transformed references
−
* '''SignatureValue''' contains the Base64 encoded value of the encrypted digest of the <code>SignedInfo</code> element
+
* '''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
 
* '''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</code>
+
* '''Object''' contains the node which is signed if the signature is of type {{Code|enveloping}}
  
 
'''Signature Types'''
 
'''Signature Types'''
  
−
Depending on the signature type, the <code>signature</code> element is either placed as a child of the signed node (<code>enveloped</code> type), or directly contains the signed node (<code>enveloping</code> type). <code>Detached</code> signatures are so far not supported.
+
Depending on the signature type, the {{Code|signature}} element is either placed as a 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'''
 
'''Digital Certificate'''
  
−
The <code>generate-signature</code> function allows to pass a <code>digital certificate</code>. 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</code> simply helps re-using the same key pair to sign and validate data. The <code>digital certificate</code> 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">
 
<pre class="brush:xml">
Line 163: Line 163:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>crypto:generate-signature</b>($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string()) as node()</code><br/><code><b>crypto:generate-signature</b>($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string()) as node()</code><br/><code><b>crypto:generate-signature</b>($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $digital-certificate as node()) as node()</code><br/><code><b>crypto:generate-signature</b>($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string(), $digital-certificate as node()) as node()</code>
+
|{{Func|crypto:generate-signature|$input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string()|node()}}<br/>{{Func|crypto:generate-signature|$input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string()|node()}}<br/>{{Func|crypto:generate-signature|$input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $digital-certificate as node()|node()}}<br/>{{Func|crypto:generate-signature|$input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string(), $digital-certificate as node()|node()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|<code>$canonicalization-algorithm</code> must either be <code>inclusive-with-comments</code>, <code>inclusive</code>, <code>exclusive-with-comments</code> or <code>exclusive</code>. <b>Default is <code>inclusive-with-comments</code></b>.<br/>
+
|{{Code|$canonicalization-algorithm}} must either be {{Code|inclusive-with-comments}}, {{Code|inclusive}}, {{Code|exclusive-with-comments}} or {{Code|exclusive}}. <b>Default is {{Code|inclusive-with-comments}}</b>.<br/>
−
<code>$digest-algorithm</code> must be one of the following: <code>SHA1</code>, <code>SHA256</code> or <code>SHA512</code>. <b>Default is <code>SHA1</code></b>.<br/>
+
{{Code|$digest-algorithm}} must be one of the following: {{Code|SHA1}}, {{Code|SHA256}} or {{Code|SHA512}}. <b>Default is {{Code|SHA1}}</b>.<br/>
−
<code>$signature-algorithm</code> must either be <code>RSA_SHA1</code> or <code>DSA_SHA1</code>. <b>Default is <code>RSA_SHA1</code></b>.<br/>
+
{{Code|$signature-algorithm}} must either be {{Code|RSA_SHA1}} or {{Code|DSA_SHA1}}. <b>Default is {{Code|RSA_SHA1}}</b>.<br/>
−
<code>$signature-namespace-prefix</code> may be empty and prefixes the <code>Signature</code> element accordingly.<br/>
+
{{Code|$signature-namespace-prefix}} may be empty and prefixes the {{Code|Signature}} element accordingly.<br/>
−
<code>$signature-type</code> must either be <code>enveloped</code> or <code>enveloping</code>. Detached signatures are so far not supported. <b>Default is <code>enveloped</code></b>.<br/>
+
{{Code|$signature-type}} must either be {{Code|enveloped}} or {{Code|enveloping}}. Detached signatures are so far not supported. <b>Default is {{Code|enveloped}}</b>.<br/>
−
<code>$xpath-expression</code> is an arbitrary XPath expression which specifies a subset of the document that is to be signed.<br/>
+
{{Code|$xpath-expression}} is an arbitrary XPath expression which specifies a subset of the document that is to be signed.<br/>
−
<code>$digital-certificate</code> is the digitial certificate used to sign the input document.
+
{{Code|$digital-certificate}} is the digitial certificate used to sign the input document.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 178: Line 178:
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0002]]</b> is raised if the digest algorithm is not supported.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0002]]</b> is raised if the digest algorithm is not supported.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0003]]</b> is raised if the signature algorithm is not supported.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0003]]</b> is raised if the signature algorithm is not supported.<br/>
−
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0004]]</b> is raised if the <code>$xpath-expression</code> is invalid.<br/>
+
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0004]]</b> is raised if the {{Code|$xpath-expression}} is invalid.<br/>
−
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0005]]</b> is raised if the root name of <code>$digital-certificate</code> is not 'digital-certificate.<br/>
+
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0005]]</b> is raised if the root name of {{Code|$digital-certificate}} is not 'digital-certificate.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0007]]</b> is raised if the key store is null.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0007]]</b> is raised if the key store is null.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0012]]</b> is raised if the key cannot be found in the specified key store.<br/>
 
<b>[[XQuery Errors#Cryptographic Functions Errors|FOCX0012]]</b> is raised if the key cannot be found in the specified key store.<br/>
Line 232: Line 232:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
−
|<code><b>crypto:validate-signature</b>($input-doc as node()) as xs:boolean()</code>
+
|{{Func|crypto:validate-signature|$input-doc as node()|xs:boolean()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
−
|Checks if the given node contains a <code>Signature</code> element and whether the signature is valid. In this case <code>true</code> is returned. If the signature is invalid the function returns <code>false</code>.
+
|Checks if the given node contains a {{Code|Signature}} element and whether the signature is valid. In this case {{Code|true}} is returned. If the signature is invalid the function returns {{Code|false}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
Line 263: Line 263:
 
! width="95%"|Description
 
! width="95%"|Description
 
|-
 
|-
−
|<code>FOCX0001</code>
+
|{{Code|FOCX0001}}
 
|The canonicalization algorithm is not supported.
 
|The canonicalization algorithm is not supported.
 
|-
 
|-
−
|<code>FOCX0002</code>
+
|{{Code|FOCX0002}}
 
|The digest algorithm is not supported.
 
|The digest algorithm is not supported.
 
|-
 
|-
−
|<code>FOCX0003</code>
+
|{{Code|FOCX0003}}
 
|The signature algorithm is not supported.
 
|The signature algorithm is not supported.
 
|-
 
|-
−
|<code>FOCX0004</code>
+
|{{Code|FOCX0004}}
 
|The XPath expression is invalid.
 
|The XPath expression is invalid.
 
|-
 
|-
−
|<code>FOCX0005</code>
+
|{{Code|FOCX0005}}
 
|The root element of argument $digital-certificate must have the name 'digital-certificate'.
 
|The root element of argument $digital-certificate must have the name 'digital-certificate'.
 
|-
 
|-
−
|<code>FOCX0006</code>
+
|{{Code|FOCX0006}}
 
|The child element of argument $digital-certificate having position $position must have the name $child-element-name.
 
|The child element of argument $digital-certificate having position $position must have the name $child-element-name.
 
|-
 
|-
−
|<code>FOCX0007</code>
+
|{{Code|FOCX0007}}
 
|The keystore is null.
 
|The keystore is null.
 
|-
 
|-
−
|<code>FOCX0008</code>
+
|{{Code|FOCX0008}}
 
|I/O error while reading keystore.
 
|I/O error while reading keystore.
 
|-
 
|-
−
|<code>FOCX0009</code>
+
|{{Code|FOCX0009}}
 
|Permission denied to read keystore.
 
|Permission denied to read keystore.
 
|-
 
|-
−
|<code>FOCX0010</code>
+
|{{Code|FOCX0010}}
 
|The keystore URL is invalid.
 
|The keystore URL is invalid.
 
|-
 
|-
−
|<code>FOCX0011</code>
+
|{{Code|FOCX0011}}
 
|The keystore type is not supported.
 
|The keystore type is not supported.
 
|-
 
|-
−
|<code>FOCX0012</code>
+
|{{Code|FOCX0012}}
 
|Cannot find key for alias in given keystore.
 
|Cannot find key for alias in given keystore.
 
|-
 
|-
−
|<code>FOCX0013</code>
+
|{{Code|FOCX0013}}
 
|The hashing algorithm is not supported.
 
|The hashing algorithm is not supported.
 
|-
 
|-
−
|<code>FOCX0014</code>
+
|{{Code|FOCX0014}}
 
|The encoding method is not supported.
 
|The encoding method is not supported.
 
|-
 
|-
−
|<code>FOCX0015</code>
+
|{{Code|FOCX0015}}
 
|Cannot find Signature element.
 
|Cannot find Signature element.
 
|-
 
|-
−
|<code>FOCX0016</code>
+
|{{Code|FOCX0016}}
 
|No such padding.
 
|No such padding.
 
|-
 
|-
−
|<code>FOCX0017</code>
+
|{{Code|FOCX0017}}
 
|Incorrect padding.
 
|Incorrect padding.
 
|-
 
|-
−
|<code>FOCX0018</code>
+
|{{Code|FOCX0018}}
 
|The encryption type is not supported.
 
|The encryption type is not supported.
 
|-
 
|-
−
|<code>FOCX0019</code>
+
|{{Code|FOCX0019}}
 
|The secret key is invalid.
 
|The secret key is invalid.
 
|-
 
|-
−
|<code>FOCX0020</code>
+
|{{Code|FOCX0020}}
 
|Illegal block size.
 
|Illegal block size.
 
|-
 
|-
−
|<code>FOCX0021</code>
+
|{{Code|FOCX0021}}
 
|The algorithm is not supported.
 
|The algorithm is not supported.
 
|-
 
|-
−
|<code>FOCX0023</code>
+
|{{Code|FOCX0023}}
 
|An invalid certificate alias is specified. Added to the official specification.
 
|An invalid certificate alias is specified. Added to the official specification.
 
|-
 
|-
−
|<code>FOCX0024</code>
+
|{{Code|FOCX0024}}
 
|The algorithm is invalid. Added to the official specification.
 
|The algorithm is invalid. Added to the official specification.
 
|-
 
|-
−
|<code>FOCX0025</code>
+
|{{Code|FOCX0025}}
 
|Signature cannot be processed. Added to the official specification.
 
|Signature cannot be processed. Added to the official specification.
 
|-
 
|-
−
|<code>FOCX0026</code>
+
|{{Code|FOCX0026}}
 
|Keystore cannot be processed. Added to the official specification.
 
|Keystore cannot be processed. Added to the official specification.
 
|-
 
|-
−
|<code>FOCX0027</code>
+
|{{Code|FOCX0027}}
 
|An I/O Exception occurred. Added to the official specification.
 
|An I/O Exception occurred. Added to the official specification.
 
|-
 
|-
−
|<code>FOCX0028</code>
+
|{{Code|FOCX0028}}
 
|The specified signature type is not supported. Added to the official specification.
 
|The specified signature type is not supported. Added to the official specification.
 
|}
 
|}

Revision as of 15:38, 26 May 2012

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($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string()) as xs:string()
crypto:hmac($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string(), $encoding as xs:string()) as xs:string()
Summary Creates a message authentication code via a cryptographic hash function and a secret key.

$encoding must either be hex, base64 or the empty string and specifies the encoding of the returned authentication code. Default is base64.
$algorithm describes the hash algorithm which is used for encryption. Currently supported are md5, sha1, sha256, sha384, sha512. Default is md5.

Errors FOCX0013 is raised if the specified hashing algorithm is not supported.

FOCX0014 is raised if the specified encoding method is not supported.
FOCX0019 is raised if the specified secret key is invalid.

Example Returns the message authentication code (MAC) for a given string.

Query: 

crypto:hmac('message','secretkey','md5','base64')

Result: 

34D1E3818B347252A75A4F6D747B21C2

Encryption & Decryption

The encryption and decryption functions underlie several limitations:

  • Cryptographic algorithms are currently limited to symmetric algorithms only. 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($input as xs:string(), $encryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()
Summary Encrypts the given input string.

$encryption-type must be symmetric, as asymmetric encryption is not supported so far. Default is symmetric.
$secret-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: 8 bytes for DES, 16 bytes for AES.
$cryptographic-algorithm must either be DES or AES. Other algorithms are not supported so far, but, of course, can be added on demand. Default is DES.

Errors FOCX0016 is raised if padding problems arise.

FOCX0017 is raised if padding is incorrect.
FOCX0018 is raised if the encryption type is not supported.
FOCX0019 is raised if the secret key is invalid.
FOCX0020 is raised if the block size is incorrect.
FOCX0021 is raised if the specified encryption algorithm is not supported.

Example Encrypts input data.

Query: 

crypto:encrypt('message', 'symmetric','keykeyke','DES')

crypto:decrypt

Signatures crypto:decrypt($input as xs:string(), $decryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()
Summary Decrypts the encrypted $input.

$decryption-type must be symmetric. An option for asymmetric encryption will most likely be added with another version of BaseX. Default is symmetric.
$secret-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: 8 bytes for DES, 16 bytes for AES.
$cryptographic-algorithm must either be DES or AES. Other algorithms are not supported so far, but, of course, can be added on demand. Default is DES.

Errors FOCX0016 is raised if padding problems arise.

FOCX0017 is raised if padding is incorrect.
FOCX0018 is raised if the encryption type is not supported.
FOCX0019 is raised if the secret key is invalid.
FOCX0020 is raised if the block size is incorrect.
FOCX0021 is raised if the specified encryption algorithm is not supported.

Example Decrypts input data and returns the original string.

Query: 

let $encrypted := crypto:encrypt('message', 'symmetric','keykeyke','DES')
return crypto:decrypt($encrypted, 'symmetric','keykeyke','DES')

Result: 

message

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 

<Signature>
  <SignedInfo>
    <CanonicalizationMethod/>
    <SignatureMethod/>
    <Reference>
      <Transforms/>
      <DigestMethod/>
      <DigestValue/>
    </Reference>
    <Reference/>
  </SignedInfo>
  <SignatureValue/>
  <KeyInfo/>
  <Object/>
</Signature>
  • 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: 

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

crypto:generate-signature

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

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

Errors FOCX0001 is raised if the canonicalization algorithm is not supported.

FOCX0002 is raised if the digest algorithm is not supported.
FOCX0003 is raised if the signature algorithm is not supported.
FOCX0004 is raised if the $xpath-expression is invalid.
FOCX0005 is raised if the root name of $digital-certificate is not 'digital-certificate.
FOCX0007 is raised if the key store is null.
FOCX0012 is raised if the key cannot be found in the specified key store.
FOCX0023 is raised if the certificate alias is invalid.
FOCX0024 is raised if an invalid algorithm is specified.
FOCX0025 is raised if an exception occurs while the signing the document.
FOCX0026 is raised if an exception occurs during key store initialization.
FOCX0027 is raised if an IO exception occurs.
FOCX0028 is raised if the signature type is not supported.

Example Generates an XML Signature.

Query: 

crypto:generate-signature(<a/>, '', '', '', '', '')

Result: 

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

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 FOCX0015 is raised if the signature element cannot be found.

FOCX9994 is raised if an unspecified problem occurs during validation.
FOCX9996 is raised if an IO exception occurs during validation.

Example Validates an XML Signature.

Query: 

let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')
return crypto:validate-signature($sig)

Result: 

true

Errors

Code Description
FOCX0001 The canonicalization algorithm is not supported.
FOCX0002 The digest algorithm is not supported.
FOCX0003 The signature algorithm is not supported.
FOCX0004 The XPath expression is invalid.
FOCX0005 The root element of argument $digital-certificate must have the name 'digital-certificate'.
FOCX0006 The child element of argument $digital-certificate having position $position must have the name $child-element-name.
FOCX0007 The keystore is null.
FOCX0008 I/O error while reading keystore.
FOCX0009 Permission denied to read keystore.
FOCX0010 The keystore URL is invalid.
FOCX0011 The keystore type is not supported.
FOCX0012 Cannot find key for alias in given keystore.
FOCX0013 The hashing algorithm is not supported.
FOCX0014 The encoding method is not supported.
FOCX0015 Cannot find Signature element.
FOCX0016 No such padding.
FOCX0017 Incorrect padding.
FOCX0018 The encryption type is not supported.
FOCX0019 The secret key is invalid.
FOCX0020 Illegal block size.
FOCX0021 The algorithm is not supported.
FOCX0023 An invalid certificate alias is specified. Added to the official specification.
FOCX0024 The algorithm is invalid. Added to the official specification.
FOCX0025 Signature cannot be processed. Added to the official specification.
FOCX0026 Keystore cannot be processed. Added to the official specification.
FOCX0027 An I/O Exception occurred. Added to the official specification.
FOCX0028 The specified signature type is not supported. Added to the official specification.

Changelog

The Module was introduced with Version 7.0.

Retrieved from "http://docs.basex.org/index.php?title=Cryptographic_Module&oldid=7250"