Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 9.3:}} argument types relaxed.
{{Mark|Updated with Version 9.3:}} argument types relaxed, return type changed to <code>xs:base64Binary</code> (before: <code>xs:string</code>).
{{Mark|Updated with Version 9.3:}} argument types relaxed.
no edit summary
==crypto:hmac==
{| width='100%'
|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}}'''.
|-
| '''Errors'''
|-
| '''Example'''
|'''Returns the Return message authentication code (MAC) for a given string.''':
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">crypto:hmac('message','secretkey','md5','base64hex')</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
34D1E3818B347252A75A4F6D747B21C2
</presyntaxhighlight>
|}
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|desDES}} and {{Code|aesAES}}.
* 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.
==crypto:encrypt==
{| width='100%'
* {{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|desDES}}, 16 bytes for {{Code|aesAES}}.* {{Code|$algorithm}} must either be {{Code|desDES}} or {{Code|aesAES}}. Default is {{Code|desDES}}.
|-
| '''Errors'''
|-
| '''Example'''
|'''Encrypts Encrypt input data.''' '''Query:'''<pre classsyntaxhighlight lang="brush:xquery">crypto:encrypt('message', 'symmetric', 'keykeyke', 'desDES')</presyntaxhighlight>
|}
==crypto:decrypt==
{| width='100%'
* {{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|desDES}}, 16 bytes for {{Code|aesAES}}.* {{Code|$algorithm}} must either be {{Code|desDES}} or {{Code|aesAES}}. Default is {{Code|desDES}}.
|-
| '''Errors'''
|-
| '''Example'''
|'''Decrypts Decrypt input data and returns the return original string.''':
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeyke', 'desDES')return crypto:decrypt($encrypted, 'symmetric', 'keykeyke', 'desDES')</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
message
</presyntaxhighlight>
|}
=XML Signatures=
[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.
'''XML Signature'''
<pre classsyntaxhighlight lang="brush:xml">
<Signature>
<SignedInfo>
<Object/>
</Signature>
</presyntaxhighlight>
* '''SignedInfo''' contains or references the signed data and lists algorithm information
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 classsyntaxhighlight lang="brush:xml">
<digital-certificate>
<keystore-type>JKS</keystore-type>
<keystore-uri>...</keystore-uri>
</digital-certificate>
</presyntaxhighlight>
==crypto:generate-signature==
|-
| '''Example'''
|'''Generates an Generate [httphttps://www.w3.org/TR/xmldsig-core/ XML Signature].''':
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">
crypto:generate-signature(<a/>, '', '', '', '', '')
</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
<a>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
</Signature>
</a>
</presyntaxhighlight>
|}
|-
| '''Example'''
|'''Validates an Validate [httphttps://www.w3.org/TR/xmldsig-core/ XML Signature].''':
'''Query:'''
<pre classsyntaxhighlight lang="brush:xquery">
let $sig := crypto:generate-signature(<a/>, '', '', '', '', '')
return crypto:validate-signature($sig)
</presyntaxhighlight>
'''Result:'''
<pre classsyntaxhighlight lang="brush:xml">
true
</presyntaxhighlight>
|}
;Version 9.3
* Updated: [[#crypto:hmac|crypto:hmac]], [[#crypto:encrypt|crypto:encrypt]], [[#crypto:decrypt|crypto:decrypt]]: Function types revised.
;Version 8.6
* Updated: [[#crypto:hmac|crypto:hmac]]: The key can now be a string or a binary item.
The Module was introduced with Version 7.0.
