Cryptographic Functions

This 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

crypto:hmac(
  $data       as xs:anyAtomicType,
  $key        as xs:anyAtomicType,
  $algorithm  as xs:string,
  $encoding   as xs:string?        := ()
) as xs:string

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

Encryption & Decryption

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

crypto:encrypt(
  $data       as xs:anyAtomicType,
  $type       as xs:string,
  $key        as xs:anyAtomicType,
  $algorithm  as xs:string
) as xs:base64Binary

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

crypto:decrypt

crypto:decrypt(
  $data       as xs:anyAtomicType,
  $type       as xs:string,
  $key        as xs:anyAtomicType,
  $algorithm  as xs:string
) as xs:string

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

XML Signatures

<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

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.

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

crypto:generate-signature(
  $input             as node(),
  $canonicalization  as xs:string,
  $as                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()

crypto:validate-signature

crypto:validate-signature(
  $input-doc  as node()
) as xs:boolean

Errors

Changelog

• Updated: crypto:hmac, crypto:encrypt, crypto:decrypt: Function types revised.
• Updated: crypto:hmac: The key can now be a string or a binary item.
• > Version 8.6:

  Version 8.6

• Added: New module added.