Difference between revisions of "Cryptographic Module"
m (→crypto:encrypt) |
m (Text replacement - "syntaxhighlight" to "pre") |
||
(98 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | This | + | 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: | + | 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. |
− | |||
− | |||
− | |||
− | |||
− | =Message Authentication | + | =Conventions= |
+ | |||
+ | 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><nowiki>http://expath.org/ns/error</nowiki></code> namespace, which is statically bound to the {{Code|experr}} prefix. | ||
+ | |||
+ | =Message Authentication= | ||
==crypto:hmac== | ==crypto:hmac== | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>crypto:hmac( | ||
+ | $data as xs:anyAtomicType, | ||
+ | $key as xs:anyAtomicType, | ||
+ | $algorithm as xs:string, | ||
+ | $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:''' | '''Query:''' | ||
− | <pre | + | <pre lang='xquery'> |
− | crypto:hmac('message','secretkey','md5',' | + | crypto:hmac('message', 'secretkey', 'md5', 'hex') |
</pre> | </pre> | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
34D1E3818B347252A75A4F6D747B21C2 | 34D1E3818B347252A75A4F6D747B21C2 | ||
</pre> | </pre> | ||
Line 39: | Line 44: | ||
=Encryption & Decryption= | =Encryption & Decryption= | ||
+ | |||
The encryption and decryption functions underlie several limitations: | The encryption and decryption functions underlie several limitations: | ||
− | * Cryptographic algorithms are limited to | + | * 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 | + | * Available algorithms are {{Code|DES}} and {{Code|AES}}. |
− | * Padding is fixed to | + | * 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 | + | * 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== | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | ''' | + | {| width='100%' |
− | < | + | |- valign="top" |
− | crypto:encrypt('message', 'symmetric','keykeyke','DES') | + | | width='120' | '''Signature''' |
+ | |<pre>crypto:encrypt( | ||
+ | $data as xs:anyAtomicType, | ||
+ | $type as xs:string, | ||
+ | $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> | </pre> | ||
|} | |} | ||
==crypto:decrypt== | ==crypto:decrypt== | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | {| width='100%' | ||
+ | |- valign="top" | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>crypto:decrypt( | ||
+ | $data as xs:anyAtomicType, | ||
+ | $type as xs:string, | ||
+ | $key as xs:anyAtomicType, | ||
+ | $algorithm as xs:string | ||
+ | ) as xs:string</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''' | ||
+ | |Decrypt input data and return original string: | ||
'''Query:''' | '''Query:''' | ||
− | <pre | + | <pre 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> | </pre> | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
message | message | ||
</pre> | </pre> | ||
|} | |} | ||
− | =XML | + | =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. | + | |
+ | [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 | + | <pre lang="xml"> |
<Signature> | <Signature> | ||
<SignedInfo> | <SignedInfo> | ||
Line 132: | Line 140: | ||
</pre> | </pre> | ||
− | * '''SignedInfo''' contains or references the signed data and | + | * '''SignedInfo''' contains or references the signed data and lists algorithm information |
− | * '''Reference''' | + | * '''Reference''' references the signed node |
− | * '''Transforms''' | + | * '''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 | + | * '''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 | + | * '''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 | + | 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 | + | 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 | + | <pre lang="xml"> |
<digital-certificate> | <digital-certificate> | ||
− | <keystore-type> | + | <keystore-type>JKS</keystore-type> |
<keystore-password>...</keystore-password> | <keystore-password>...</keystore-password> | ||
<key-alias>...</key-alias> | <key-alias>...</key-alias> | ||
Line 159: | Line 167: | ||
==crypto:generate-signature== | ==crypto:generate-signature== | ||
− | {| | + | |
− | |- | + | {| width='100%' |
− | + | |- valign="top" | |
− | |< | + | | width='120' | '''Signature''' |
− | |- | + | |<pre>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, | |
− | + | $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}}'''.<br/> | |
− | + | {{Code|$digest}} must be one of the following: {{Code|SHA1}}, {{Code|SHA256}} or {{Code|SHA512}}. '''Default is {{Code|SHA1}}'''.<br/> | |
− | + | {{Code|$signature}} must either be {{Code|RSA_SHA1}} or {{Code|DSA_SHA1}}. '''Default is {{Code|RSA_SHA1}}'''.<br/> | |
− | + | {{Code|$prefix}} may be empty and prefixes the {{Code|Signature}} element accordingly.<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|$ext1}} may either be an {{Code|$xpath}} expression or a {{Code|$certificate}}.<br/> | |
− | + | 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 {{Code|$ext2}} is the digitial certificate used to sign the input 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''' | |
− | |- | + | |Generate [https://www.w3.org/TR/xmldsig-core/ XML Signature]: |
− | |||
− | | | ||
'''Query:''' | '''Query:''' | ||
− | <pre | + | <pre lang='xquery'> |
crypto:generate-signature(<a/>, '', '', '', '', '') | crypto:generate-signature(<a/>, '', '', '', '', '') | ||
</pre> | </pre> | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
<a> | <a> | ||
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> | <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> | ||
Line 228: | Line 234: | ||
==crypto:validate-signature== | ==crypto:validate-signature== | ||
− | {| | + | |
− | |- | + | {| width='100%' |
− | + | |- valign="top" | |
− | |< | + | | width='120' | '''Signature''' |
− | |- | + | |<pre>crypto:validate-signature( |
− | + | $input-doc as node() | |
− | |Checks if the given node contains a | + | ) as xs:boolean</pre> |
− | |- | + | |- valign="top" |
− | + | | '''Summary''' | |
− | | | + | |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}}. |
− | + | |- valign="top" | |
− | + | | '''Errors''' | |
− | |- | + | |{{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/> |
− | + | |- valign="top" | |
− | | | + | | '''Example''' |
+ | |Validate [https://www.w3.org/TR/xmldsig-core/ XML Signature]: | ||
'''Query:''' | '''Query:''' | ||
− | <pre | + | <pre lang='xquery'> |
let $sig := crypto:generate-signature(<a/>, '', '', '', '', '') | let $sig := crypto:generate-signature(<a/>, '', '', '', '', '') | ||
return crypto:validate-signature($sig) | return crypto:validate-signature($sig) | ||
Line 251: | Line 258: | ||
'''Result:''' | '''Result:''' | ||
− | <pre | + | <pre lang="xml"> |
true | true | ||
</pre> | </pre> | ||
|} | |} | ||
+ | |||
+ | =Errors= | ||
+ | |||
+ | {| class="wikitable" width="100%" | ||
+ | ! width="110"|Code | ||
+ | |Description | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0001}} | ||
+ | |The canonicalization algorithm is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0002}} | ||
+ | |The digest algorithm is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0003}} | ||
+ | |The signature algorithm is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0004}} | ||
+ | |The XPath expression is invalid. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0005}} | ||
+ | |The root element of argument $digital-certificate must have the name 'digital-certificate'. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0006}} | ||
+ | |The child element of argument $digital-certificate having position $position must have the name $child-element-name. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0007}} | ||
+ | |The keystore is null. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0008}} | ||
+ | |I/O error while reading keystore. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0009}} | ||
+ | |Permission denied to read keystore. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0010}} | ||
+ | |The keystore URL is invalid. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0011}} | ||
+ | |The keystore type is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0012}} | ||
+ | |Cannot find key for alias in given keystore. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0013}} | ||
+ | |The hashing algorithm is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0014}} | ||
+ | |The encoding method is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0015}} | ||
+ | |Cannot find Signature element. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0016}} | ||
+ | |No such padding. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0017}} | ||
+ | |Incorrect padding. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0018}} | ||
+ | |The encryption type is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0019}} | ||
+ | |The secret key is invalid. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0020}} | ||
+ | |Illegal block size. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0021}} | ||
+ | |The algorithm is not supported. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0023}} | ||
+ | |An invalid certificate alias is specified. Added to the official specification. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0024}} | ||
+ | |The algorithm is invalid. Added to the official specification. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0025}} | ||
+ | |Signature cannot be processed. Added to the official specification. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0026}} | ||
+ | |Keystore cannot be processed. Added to the official specification. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0027}} | ||
+ | |An I/O Exception occurred. Added to the official specification. | ||
+ | |- valign="top" | ||
+ | |{{Code|CX0028}} | ||
+ | |The specified signature type is not supported. Added to the official specification. | ||
+ | |} | ||
+ | |||
+ | =Changelog= | ||
+ | |||
+ | ;Version 9.3 | ||
+ | * Updated: {{Function||crypto:hmac}}, {{Function||crypto:encrypt}}, {{Function||crypto:decrypt}}: Function types revised. | ||
+ | |||
+ | ;Version 8.6 | ||
+ | * Updated: {{Function||crypto:hmac}}: The key can now be a string or a binary item. | ||
+ | |||
+ | The Module was introduced with Version 7.0. |
Latest revision as of 18:39, 1 December 2023
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.
Contents
Conventions[edit]
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[edit]
crypto:hmac[edit]
Signature | 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:
|
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: crypto:hmac('message', 'secretkey', 'md5', 'hex')
Result: 34D1E3818B347252A75A4F6D747B21C2
|
Encryption & Decryption[edit]
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
andAES
. - 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 thecrypto:decrypt
function.
crypto:encrypt[edit]
Signature | 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:
|
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:
crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')
|
crypto:decrypt[edit]
Signature | 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:
|
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: let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeyke', 'DES')
return crypto:decrypt($encrypted, 'symmetric', 'keykeyke', 'DES')
Result: message
|
XML Signatures[edit]
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[edit]
Signature | 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, $ext1 as item(), $ext2 as node() ) as node() |
Summary | $canonicalization must either be inclusive-with-comments , inclusive , exclusive-with-comments or exclusive . Default is inclusive-with-comments .
|
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: 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[edit]
Signature | 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: let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')
return crypto:validate-signature($sig)
Result: true
|
Errors[edit]
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[edit]
- Version 9.3
- Updated:
crypto:hmac
,crypto:encrypt
,crypto:decrypt
: Function types revised.
- 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.