Cryptographic Functions

This module contains functions to perform cryptographic operations in XQuery. The cryptographic module was based on a draft of the EXPath Cryptographic Module. It provides the following functionality: creation of message authentication codes (HMAC), derivation of keys from passwords, encryption and decryption, and creation and validation of XML Digital Signatures.

Conventions

All functions are in the http://expath.org/ns/crypto namespace, to which the crypto prefix is statically bound.

All errors are in the http://expath.org/ns/error namespace, to which the experr prefix is statically bound.

Message Authentication

crypto:hmac

crypto:hmac(  $value      as (xs:string | xs:base64Binary | xs:hexBinary),  $key        as (xs:string | xs:base64Binary | xs:hexBinary),  $algorithm  as xs:string,  $encoding   as xs:string?  := ()) as xs:string

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

Key Derivation

crypto:pbkdf2

Added: New function.

crypto:pbkdf2(  $password    as xs:string,  $salt        as (xs:string | xs:base64Binary | xs:hexBinary),  $iterations  as xs:integer,  $length      as xs:integer,  $algorithm   as xs:string?  := ()) as xs:hexBinary

crypto:pbkdf2('password', 'salt', 4096, 32)

let $salt := random:uuid()
let $key := crypto:pbkdf2('secret', $salt, 600000, 32)
return db:put-value('users', { 'salt': $salt, 'key': $key }, 'jane')

Encryption & Decryption

The encryption and decryption functions underlie several limitations:

• Available symmetric algorithms (the same secret key is used for encryption and decryption) are AES (CBC mode with PKCS5Padding) and AES-GCM (GCM mode; authenticated encryption, which detects tampered data on decryption). The key must have 16, 24 or 32 bytes.
• The only asymmetric algorithm is RSA (OAEP padding with SHA-256). Data is encrypted with a public key and decrypted with the corresponding private key. The keys are passed as strings in PEM format (-----BEGIN PUBLIC KEY-----, -----BEGIN PRIVATE KEY-----) or as binary items in DER format (X.509 for public keys, PKCS #8 for private keys). The data must be shorter than the key size minus 66 bytes, e.g. 190 bytes for a 2048-bit key.
• The result of a symmetric 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 prepended 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

Updated: AES-GCM and RSA added; DES removed.

crypto:encrypt(  $value      as (xs:string | xs:base64Binary | xs:hexBinary),  $type       as xs:string,  $key        as (xs:string | xs:base64Binary | xs:hexBinary),  $algorithm  as xs:string) as xs:base64Binary

crypto:encrypt('message', 'symmetric', 'keykeykeykeykeyk', 'AES-GCM')

crypto:encrypt('message', 'asymmetric', file:read-text('public.pem'), 'RSA')

crypto:decrypt

Updated: AES-GCM and RSA added; DES removed.

crypto:decrypt(  $value      as (xs:string | xs:base64Binary | xs:hexBinary),  $type       as xs:string,  $key        as (xs:string | xs:base64Binary | xs:hexBinary),  $algorithm  as xs:string) as xs:string

let $encrypted := crypto:encrypt('message', 'symmetric', 'keykeykeykeykeyk', 'AES-GCM')
return crypto:decrypt($encrypted, 'symmetric', 'keykeykeykeykeyk', 'AES-GCM')

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

Updated: New algorithms RSA_SHA256, RSA_SHA512 and DSA_SHA256; new defaults SHA256 and RSA_SHA256.

crypto:generate-signature(  $node              as xnode(),  $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 xnode()  := ()) as document-node()

crypto:validate-signature

crypto:validate-signature(  $node  as xnode()) as xs:booleancreate

Errors

Changelog

• Added: crypto:pbkdf2.
• Updated: crypto:encrypt, crypto:decrypt: AES-GCM and RSA added; DES removed; algorithm names are case-insensitive.
• Updated: crypto:generate-signature: RSA_SHA256, RSA_SHA512 and DSA_SHA256 added; defaults changed to SHA256 and RSA_SHA256.

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

• Added: New module added.