Difference between revisions of "Cryptographic Module"
Line 17: | Line 17: | ||
| '''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}} must either be {{Code|hex}}, {{Code|base64}} or the empty string and specifies the encoding of the returned authentication code. | + | {{Code|$encoding}} must either 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}}. | + | {{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}}'''. |
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | | | + | |{{Error|FOCX0013|XQuery Errors#Cryptographic Functions Errors}} the specified hashing algorithm is not supported.<br/> |
− | + | {{Error|FOCX0014|XQuery Errors#Cryptographic Functions Errors}} the specified encoding method is not supported.<br/> | |
− | + | {{Error|FOCX0019|XQuery Errors#Cryptographic Functions Errors}} the specified secret key is invalid.<br/> | |
|- | |- | ||
| '''Example''' | | '''Example''' | ||
Line 55: | Line 55: | ||
| '''Summary''' | | '''Summary''' | ||
|Encrypts the given input string.<br/> | |Encrypts the given input string.<br/> | ||
− | {{Code|$encryption-type}} must be {{Code|symmetric}}, as asymmetric encryption is not supported so far. | + | {{Code|$encryption-type}} must be {{Code|symmetric}}, as asymmetric encryption is not supported so far. '''Default is {{Code|symmetric}}'''.<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|$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}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. | + | {{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. '''Default is {{Code|DES}}'''. |
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | | | + | |{{Error|FOCX0016|XQuery Errors#Cryptographic Functions Errors}} padding problems arise.<br/> |
− | + | {{Error|FOCX0017|XQuery Errors#Cryptographic Functions Errors}} padding is incorrect.<br/> | |
− | + | {{Error|FOCX0018|XQuery Errors#Cryptographic Functions Errors}} the encryption type is not supported.<br/> | |
− | + | {{Error|FOCX0019|XQuery Errors#Cryptographic Functions Errors}} the secret key is invalid.<br/> | |
− | + | {{Error|FOCX0020|XQuery Errors#Cryptographic Functions Errors}} the block size is incorrect.<br/> | |
− | + | {{Error|FOCX0021|XQuery Errors#Cryptographic Functions Errors}} the specified encryption algorithm is not supported.<br/> | |
|- | |- | ||
| '''Example''' | | '''Example''' | ||
Line 84: | Line 84: | ||
| '''Summary''' | | '''Summary''' | ||
|Decrypts the encrypted {{Code|$input}}.<br/> | |Decrypts the encrypted {{Code|$input}}.<br/> | ||
− | {{Code|$decryption-type}} must be {{Code|symmetric}}. An option for asymmetric encryption will most likely be added with another version of BaseX. | + | {{Code|$decryption-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|$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|$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}} must either be {{Code|DES}} or {{Code|AES}}. Other algorithms are not supported so far, but, of course, can be added on demand. | + | {{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. '''Default is {{Code|DES}}'''. |
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | | | + | |{{Error|FOCX0016|XQuery Errors#Cryptographic Functions Errors}} padding problems arise.<br/> |
− | + | {{Error|FOCX0017|XQuery Errors#Cryptographic Functions Errors}} padding is incorrect.<br/> | |
− | + | {{Error|FOCX0018|XQuery Errors#Cryptographic Functions Errors}} the encryption type is not supported.<br/> | |
− | + | {{Error|FOCX0019|XQuery Errors#Cryptographic Functions Errors}} the secret key is invalid.<br/> | |
− | + | {{Error|FOCX0020|XQuery Errors#Cryptographic Functions Errors}} the block size is incorrect.<br/> | |
− | + | {{Error|FOCX0021|XQuery Errors#Cryptographic Functions Errors}} the specified encryption algorithm is not supported.<br/> | |
|- | |- | ||
| '''Example''' | | '''Example''' | ||
Line 166: | Line 166: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |{{Code|$canonicalization-algorithm}} must either be {{Code|inclusive-with-comments}}, {{Code|inclusive}}, {{Code|exclusive-with-comments}} or {{Code|exclusive}}. | + | |{{Code|$canonicalization-algorithm}} 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-algorithm}} must be one of the following: {{Code|SHA1}}, {{Code|SHA256}} or {{Code|SHA512}}. | + | {{Code|$digest-algorithm}} must be one of the following: {{Code|SHA1}}, {{Code|SHA256}} or {{Code|SHA512}}. '''Default is {{Code|SHA1}}'''.<br/> |
− | {{Code|$signature-algorithm}} must either be {{Code|RSA_SHA1}} or {{Code|DSA_SHA1}}. | + | {{Code|$signature-algorithm}} must either be {{Code|RSA_SHA1}} or {{Code|DSA_SHA1}}. '''Default is {{Code|RSA_SHA1}}'''.<br/> |
{{Code|$signature-namespace-prefix}} may be empty and prefixes the {{Code|Signature}} element accordingly.<br/> | {{Code|$signature-namespace-prefix}} may be empty and prefixes the {{Code|Signature}} element accordingly.<br/> | ||
− | {{Code|$signature-type}} must either be {{Code|enveloped}} or {{Code|enveloping}}. Detached signatures are so far not supported. | + | {{Code|$signature-type}} must either be {{Code|enveloped}} or {{Code|enveloping}}. Detached signatures are so far not supported. '''Default is {{Code|enveloped}}'''.<br/> |
{{Code|$xpath-expression}} 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}} 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''' | ||
− | | | + | |{{Error|FOCX0001|XQuery Errors#Cryptographic Functions Errors}} the canonicalization algorithm is not supported.<br/> |
− | + | {{Error|FOCX0002|XQuery Errors#Cryptographic Functions Errors}} the digest algorithm is not supported.<br/> | |
− | + | {{Error|FOCX0003|XQuery Errors#Cryptographic Functions Errors}} the signature algorithm is not supported.<br/> | |
− | + | {{Error|FOCX0004|XQuery Errors#Cryptographic Functions Errors}} the {{Code|$xpath-expression}} is invalid.<br/> | |
− | + | {{Error|FOCX0005|XQuery Errors#Cryptographic Functions Errors}} the root name of {{Code|$digital-certificate}} is not 'digital-certificate.<br/> | |
− | + | {{Error|FOCX0007|XQuery Errors#Cryptographic Functions Errors}} the key store is null.<br/> | |
− | + | {{Error|FOCX0012|XQuery Errors#Cryptographic Functions Errors}} the key cannot be found in the specified key store.<br/> | |
− | + | {{Error|FOCX0023|XQuery Errors#Cryptographic Functions Errors}} the certificate alias is invalid.<br/> | |
− | + | {{Error|FOCX0024|XQuery Errors#Cryptographic Functions Errors}} an invalid algorithm is specified.<br/> | |
− | + | {{Error|FOCX0025|XQuery Errors#Cryptographic Functions Errors}} an exception occurs while the signing the document.<br/> | |
− | + | {{Error|FOCX0026|XQuery Errors#Cryptographic Functions Errors}} an exception occurs during key store initialization.<br/> | |
− | + | {{Error|FOCX0027|XQuery Errors#Cryptographic Functions Errors}} an IO exception occurs.<br/> | |
− | + | {{Error|FOCX0028|XQuery Errors#Cryptographic Functions Errors}} the signature type is not supported.<br/> | |
|- | |- | ||
| '''Example''' | | '''Example''' | ||
Line 238: | Line 238: | ||
|- | |- | ||
| '''Errors''' | | '''Errors''' | ||
− | | | + | |{{Error|FOCX0015|XQuery Errors#Cryptographic Functions Errors}} the signature element cannot be found.<br/> |
− | + | {{Error|FOCX9994|XQuery Errors#Cryptographic Functions Errors}} an unspecified problem occurs during validation.<br/> | |
− | + | {{Error|FOCX9996|XQuery Errors#Cryptographic Functions Errors}} an IO exception occurs during validation.<br/> | |
|- | |- | ||
| '''Example''' | | '''Example''' |
Revision as of 15:51, 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.
Contents
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.
|
Errors | FOCX0013 : the specified hashing algorithm is not supported.
|
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
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
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.
|
Errors | FOCX0016 : padding problems arise.
|
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 .
|
Errors | FOCX0016 : padding problems arise.
|
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 .
|
Errors | FOCX0001 : the canonicalization algorithm 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 : the signature element cannot be found.
|
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.