Cryptographic Module

This proposal defines a set of XPath 2.0 extension functions to perform cryptographic operations. It defines extension functions related to XML Digital Signature, to encryption and decryption, and to hash and digest messages. It has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other standard based on XPath 2.0.

Introduction

Cryptography is the science of communicating in secret code, by conversion of data with the help of a key. In modern times, cryptography is necessary when communicating over any untrusted medium, particularly the Internet.

Encryption of data can be of two types: symmetric and asymmetric. Symmetric encryption means that the same key is used for encryption and decryption. Asymmetric encryption means that a message can be encrypted by using a key that is public, but the decryption can be made only by using a private key, which form a pair with the respective public key.

A related technique of cryptography is to apply a one-way hash or digest function to data; replicating the operation with the same data and function can ensure the integrity of the data.

This proposal defines a set of XPath 2.0 extension functions to perform these cryptographic operations. It defines extension functions related to XML Digital Signature, to encryption and decryption, and to hash and digest messages. It has been designed to be compatible with XQuery 1.0 and XSLT 2.0, as well as any other standard based on XPath 2.0.

Namespace conventions

The module defined by this document defines functions and elements in the namespace http://expath.org/ns/crypto. In this document, the crypto prefix, when used, is bound to this namespace URI.

Error codes are defined in the namespace http://expath.org/ns/error. In this document, the err prefix, when used, is bound to this namespace URI.

Error management

Error conditions are identified by a code (a QName). When such an error condition is reached during the execution of the function, a dynamic error is thrown, with the corresponding error code (as if the standard XPath function error had been called).

HMAC: Keyed-Hashing for Message Authentication

HMAC is a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function, e.g. MD5 or SHA-1, in combination with a secret shared key. Typically, message authentication codes are used between two parties that share a secret key in order to validate information transmitted between these parties.

The `crypto:hmac` function

This function generates a message authentication code, based on the input message, by using a cryptographic algorithm and a secret key.

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

$message is the message to be authenticated.
$secret-key is the secret key used for calculating the authentication code.
$algorithm is the cryptographic hashing algorithm. If the parameter specifies an unsupported algorithm, this is an error [=err:CX13=].
$encoding is the method used for encoding of the authentication code. Default value: "base64". If the parameter specifies an unsupported method, this is an error [=err:CX14=].

XML Digital Signature

The XML Signature is a method of associating a key with referenced data (octets); it does not normatively specify how keys are associated with persons or institutions, nor the meaning of the data being referenced and signed. XML Signatures are applied to arbitrary digital content (data objects) via an indirection. Data objects are digested, the resulting value is placed in an element (with other information) and that element is then digested and cryptographically signed.

The `crypto:generate-signature` function

This function has four signatures, as one have to consider that some applications require the ability to specify a subset of a given XML document as the information content to be signed (this is done by using XPath to indicate the subset), and also the ability to use a digital certificate to obtain the key pair, instead of an auto-generated key pair.

The first signature considers the case of auto-generated key pair, and signature for the whole document.

The second signature considers the case of auto-generated key pair, and signature for a subset of the document.

The third signature considers the case of key pair generated from an digital certificate, and signature for the whole document.

The fourth signature considers the case of key pair generated from an digital certificate, and signature for a subset of the document.

crypto:generate-signature($input-doc as 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 as 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 as 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 as 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()

$input-doc is the document to be signed.
$canonicalization-algorithm is the canonicalization algorithm applied to the SignedInfo element prior to performing signature calculations. Possible values are: "exclusive", "exclusive-with-comments", "inclusive", and "inclusive-with-comments". The default value is "inclusive-with-comments". If the parameter specifies an unsupported algorithm, this is an error [=err:CX01=].
$digest-algorithm is the digest algorithm to be applied to the signed object. Possible values are: "SHA1", "SHA256", and "SHA512". The default value is "SHA1". If the parameter specifies an unsupported algorithm, this is an error [=err:CX02=].
$signature-algorithm is the algorithm used for signature generation and validation. Possible values are: "DSA_SHA1", and "RSA_SHA1". The default value is "RSA_SHA1". If the parameter specifies an unsupported algorithm, this is an error [=err:CX03=].
$signature-namespace-prefix is the namespace prefix for signature.
$signature-type is the method used for signing the content of signature. Possible values are: 'enveloping', 'enveloped', and 'detached'. The default value is 'enveloped'.
$xpath-expression is the XPath expression used for selecting the subset to be signed. If the XPath expression is invalid, this is an error [=err:CX04=].
$digital-certificate is the digital certificate to be used for signing the input document or document subset. The structure of this parameter is as follows (this is an example):
```
<digital-certificate>
   <keystore-type>JKS</keystore-type>
   <keystore-password>ab987c</keystore-password>
   <key-alias>eXist</key-alias>
   <private-key-password>kpi135</private-key-password>
   <keystore-uri>/db/mykeystoreEXist</keystore-uri>
</digital-certificate>
```
The following errors can be raised relative to the structure and content of $digital-certificate parameter: [=err:CX05=], [=err:CX06=], [=err:CX07=], [=err:CX08=], [=err:CX09=], [=err:CX10=], [=err:CX11=], and [=err:CX12=].

The `crypto:validate-signature` function

This function validates an XML Digital Signature.

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

$input-doc is the enveloped, enveloping, or detached signature. If the Signature element cannot be found, this is an error [=err:CX15=].

The `crypto:generate-self-signed-certificate` function

This function generates, for development purposes, a self signed digital certificate. TODO: To be developed, if such function is of any use.

Encryption and decryption

Encryption represents the process of conversion of data, by using a secret key (a cipher), in a form (called cipher text) that cannot be understood by unautorized persons.

The decryption represents the reverse process, of converting encrypted data back to plain text (original text).

There are two main types of encryption: symmetric encryption, when both parties, the sender and the receiver, use the same secret key, previously exchanged, and asymmetric encryption, when a key pair, consisting of a private key and a private key, is used, of which the public key is used by sender to encrypt a message that can only be decrypted by the receiver, who holds the private key of that key pair.

The `crypto:encrypt` function

This function encrypts an input string.

crypto:encrypt($input-string as xs:string,
               $encryption-type as xs:string,
               $secret-key as xs:string,
               $cryptographic-algorithm as xs:string) as xs:boolean

$input-string is the string to be encrypted. When a particular padding mechanism is requested, but is not available, this is an error [=err:CX16=]. Also, when a particular padding mechanism is expected, but the data is not padded properly, this is an error [=err:CX17=].
$encryption-type is the type of encryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error [=err:CX18=].
$secret-key is the secret key used for encryption, as string. If the key is invalid, this is an error [=err:CX19=]. If the length of data provided to the block cipher is incorrect, this is an error [=err:CX20=].
$cryptographic-algorithm is the cryptographic algorithm used for encryption. If the parameter specifies an unsupported algorithm, this is an error [=err:CX21=].

The `crypto:decrypt` function

This function decrypts an input string.

crypto:decrypt($input-string as xs:string,
               $decryption-type as xs:string,
               $secret-key as xs:string,
               $cryptographic-algorithm as xs:string) as xs:boolean

$input-string is the string to be decrypted. When a particular padding mechanism is requested, but is not available, this is an error [=err:CX16=]. Also, when a particular padding mechanism is expected, but the data is not padded properly, this is an error [=err:CX17=].
$encryption-type is the type of encryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error [=err:CX22=].
$secret-key is the secret key used for encryption, as string. If the key is invalid, this is an error [=err:CX19=]. If the length of data provided to the block cipher is incorrect, this is an error [=err:CX20=].
$cryptographic-algorithm is the cryptographic algorithm used for encryption. If the parameter specifies an unsupported algorithm, this is an error [=err:CX21=]

Introduction

Namespace conventions

Error management

HMAC: Keyed-Hashing for Message Authentication

The crypto:hmac function

XML Digital Signature

The crypto:generate-signature function

The crypto:validate-signature function

The crypto:generate-self-signed-certificate function