Cryptographic Module

From BaseX Documentation
Jump to navigation Jump to search

This module contains XQuery 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:

  1. Creation of message authentication codes (HMAC)
  2. Encryption and decryption
  3. Creation and validation of an XML Digital Signature

This module is introduced with Version 7.0 of BaseX.

Message Authentication Code (MAC)

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 (default is base64) and specifies the encoding of the returned authentication code.
$algorithm describes the hash algorithm which is used for encryption. Currently supported are md5, sha1, sha256, sha384, sha512.
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:

  1. Cryptographic algorithms are limited to symmetric algorithms only. This means that the same secret key is used for encryption and decryption.
  2. Available algorithms are DES and AES.
  3. 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 which is appended to the message and simply increases security.
  4. Padding is fixed to PKCS5Padding.

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

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

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 Signature

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>

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. If not specified, the default value 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. The 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.
$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.
FOCX9992 is raised if the certificate alias is invalid.
FOCX9993 is raised if an invalid algorithm is specified.
FOCX9994 is raised if an exception occurs while the signing the document.
FOCX9995 is raised if an exception occurs during key store initialization.
FOCX9996 is raised if an IO exception occurs.
FOCX9999 is raised if the signature type is not supported.

Example Generates an XML Signature.

crypto:validate-signature

Signatures crypto:validate-signature($input-doc as node()) as xs:boolean()
Summary ?
Errors ?
Example Validates an XML Signature.