W3C

Cryptographic Module

EXPath Candidate Module 14 February 2015

This version:
http://expath.org/spec/crypto/20150214
Latest version:
http://expath.org/spec/crypto
Previous version:
http://expath.org/spec/crypto/20110810
Editor:
Claudius Teodorescu, XML Consultant
Contributor:
Joe Wicentowski, U.S. Department Of State, Historian Office

This document is also available in these non-normative formats: XML and Revision markup.


Abstract

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.

Table of Contents

1 Introduction
    1.1 Namespace conventions
    1.2 Error management
2 HMAC: Keyed-Hashing for Message Authentication
    2.1 The crypto:hmac function
3 XML Digital Signature
    3.1 The crypto:generate-signature function
    3.2 The crypto:validate-signature function
4 Encryption and decryption
    4.1 The crypto:encrypt function
    4.2 The crypto:decrypt function

Appendices

A References
B Summary of Error Conditions


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

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

1.2 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).

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

2.1 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].

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

3.1 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].

3.2 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].

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

4.1 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].

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

A References

RFC 2104
RFC 2104: HMAC: Keyed-Hashing for Message Authentication. H. Krawczyk, M. Bellare, R. Canetti, editors. Network Working Group. February, 1997.
RFC 2617
RFC 2617: HTTP Authentication: Basic and Digest Access Authentication. J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart. June, 1999.
F&O 1.1
XPath and XQuery Functions and Operators 1.1. Michael Kay, editor. W3C Working Draft. 15 January 2009.
XSLT 2.0
XSL Transformations (XSLT) Version 2.0. Michael Kay, editor. W3C Recommendation. 23 January 2007.
XML Signature
XML Signature Syntax and Processing (Second Edition). Donald Eastlake, Joseph Reagle, David Solo, Frederick Hirsch, Thomas Roessler, editors. Mark Bartel, John Boyer, Barb Fox, Brian LaMacchia, Ed Simon, authors. W3C Recommendation, 10 June 2008.
XML-Signature XPath Filter 2.0
XML-Signature XPath Filter 2.0. John Boyer, Merlin Hughes, Joseph Reagle, authors/editors. W3C Recommendation, 08 November 2002.

B Summary of Error Conditions

err:CX01
The canonicalization algorithm is not supported.
err:CX02
The digest algorithm is not supported.
err:CX03
The signature algorithm is not supported.
err:CX04
The XPath expression is invalid.
err:CX05
The root element of argument $digital-certificate must have the name 'digital-certificate'.
err:CX06
The child element of argument $digital-certificate having position $position must have the name $child-element-name.
err:CX07
The keystore is null.
err:CX08
I/O error while reading keystore.
err:CX09
Permission denied to read keystore.
err:CX10
The keystore URL is invalid.
err:CX11
The keystore type is not supported.
err:CX12
Cannot find key for alias in given keystore.
err:CX13
The hashing algorithm is not supported.
err:CX14
The encoding method is not supported.
err:CX15
Cannot find Signature element.
err:CX16
No such padding.
err:CX17
Incorrect padding.
err:CX18
The encryption type is not supported.
err:CX19
The secret key is invalid.
err:CX20
Illegal block size.
err:CX21
The algorithm is not supported.
err:CX22
The decryption type is not supported.