Cryptographic Module w3c-designation EXPath Candidate Module 14 February 2015 XML Revision markup Claudius Teodorescu XML Consultant Joe Wicentowski U.S. Department Of State, Historian Office

This proposal defines a set of XPath 3.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 3.0 and XSLT 3.0, as well as any other standard based on XPath 3.0.

Must be ignored, but is required by the schema...

langusage

revisiondesc

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.

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 same namespace (http://expath.org/ns/crypto), and in this document are displayed with the same prefix, crypto.

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

Integrity and Authentication of Data The crypto:hash function

This function generates a "message digest" of the input data, by using a cryptographic algorithm. It returns the hash value as a string.

crypto:hash($data as xs:anyAtomicType, $algorithm as xs:string) as xs:string crypto:hash($data as xs:anyAtomicType, $algorithm as xs:string, $format as xs:string?) as xs:string

$data is the data to be hashed. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary.

$algorithm is the cryptographic hashing algorithm. If it is specified an unsupported algorithm, this is an error .

$format is the format of the output. The legal values are "hex" and "base64". The default value is "base64". If the format is not supprted, this is an error .

The crypto:hmac function

HMAC (Keyed-Hashing for Message Authentication) 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.

This function generates a message authentication code, based on the input message, by using a cryptographic algorithm and a secret key. It returns the hash-based message authentication code as base64 string.

crypto:hmac($data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string) as xs:string crypto:hmac($data as xs:anyAtomicType, $key as xs:anyAtomicType, $algorithm as xs:string, $format as xs:string) as xs:string

$data is the data to be authenticated. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary.

$key is the secret key used for calculating the authentication code. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary.

$algorithm is the cryptographic hashing algorithm. If it is specified an unsupported algorithm, this is an error .

$format is the format of the output. The legal values are "hex" and "base64". The default value is "base64". If the format is not supprted, this is an error .

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

The function has its parameters passed as a map(xs:string, item()). If any of these parameters is missing, a default value will be used instead. After the function's signature, an example of parameters is given. The syntax for the $references parameter is inspired by .

crypto:generate-signature($data as node()*, $parameters as map(xs:string, item())?) as node()

Example of parameters:

map { "canonicalization-algorithm" := "inclusive-with-comments", "digest-algorithm" := "SHA1", "signature-algorithm" := "RSA_SHA1", "signature-namespace-prefix" := "dsig", "signature-type" := "enveloped", "references" := ( <Reference xmlns="http://www.w3.org/2000/09/xmldsig#" URI=""> <Transforms> <Transform Algorithm="http://www.w3.org/2002/06/xmldsig-filter2"> <XPath Filter="intersect">//ToBeSigned</XPath> <XPath Filter="subtract">//NotToBeSigned</XPath> <XPath Filter="union">//ReallyToBeSigned</XPath> </Transform> </Transforms> </Reference>, <Reference xmlns="http://www.w3.org/2000/09/xmldsig#" URI="#id"> <Transforms> <Transform Algorithm="http://www.w3.org/TR/2001/10/xml-exc-c14n" /> </Transforms> </Reference> ) "digital-certificate" := map { "keystore-type" := "JKS", "keystore-password" := "password", "key-alias" := "alias", "private-key-password" := "password", "keystore-url" := "/db/mykeystore" } }

$data is the data 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 .

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

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

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

$references represents the resources to be signed. If this parameter is missing, the whole input document will be signed.

$digital-certificate is the digital certificate to be used for signing the references. If this parameter is missing, an auto-generated key pair will be used. The components of this parameter are:

keystore-type is the keystore type. If the type is not supported, this is an error .

keystore-password is the keystore's password. If the keystore cannot be loaded or the password is incorrect, this is an error .

key-alias is the alias for the key pair used for signing. If no key pair exists for this alias, this is an error .

private-key-password is the password for the selected key.

keystore-url is the URL of the keystore. If the URL is not correct, this is an error . If the user has no acces to the keystore, this is an error .

The crypto:validate-signature function

This function validates an XML Digital Signature.

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

$data is the enveloped, enveloping, or detached signature. If the Signature element cannot be found, this is an error .

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

crypto:encrypt($data as xs:anyAtomicType, $type as xs:string, $parameters as map(xs:string, item())?) as xs:anyAtomicType

$data is the data to be encrypted. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary. When a particular padding mechanism is requested, but is not available, this is an error . Also, when a particular padding mechanism is expected, but the data is not padded properly, this is an error .

$type is the type of encryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error .

$parameters represents the parameters needed for the current operation. The parameters are the following:

key as xs:anyAtomicType is the cryptographic key used for encryption. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary. If the key is invalid, this is an error . If the length of data provided to the block cipher is incorrect, this is an error .

algorithm as xs:string is the cryptographic algorithm used for encryption. For symmetric encryption, a transformation name can be used. If the parameter specifies an unsupported algorithm or transformation name, this is an error .

iv as xs:string is the initialization vector for symmetric encryption.

provider as xs:string is the cryptographic provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error .

The crypto:decrypt function

This function decrypts data.

crypto:decrypt($data as xs:anyAtomicType, $type as xs:string, $parameters as map(xs:string, item())?) as xs:anyAtomicType

$data is the data to be decrypted. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary. When a particular padding mechanism is requested, but is not available, this is an error . Also, when a particular padding mechanism is expected, but the data is not padded properly, this is an error .

$type is the type of decryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error .

$parameters represents the parameters needed for the current operation. The parameters are the following:

key as xs:anyAtomicType is the cryptographic key used for decryption. This parameter can be of type xs:string, xs:base64Binary, or xs:hexBinary. If the key is invalid, this is an error . If the length of data provided to the block cipher is incorrect, this is an error .

algorithm as xs:string is the cryptographic algorithm used for decryption. For symmetric decryption, a transformation name can be used. If the parameter specifies an unsupported algorithm or transformation name, this is an error .

iv as xs:string? is the initialization vector for symmetric encryption.

provider as xs:string is the cryptographic provider for the current operation. If the provider is not specified, the implementation will use the default provider. If the provider does not exist, this is an error .

References XML Path Language (XPath) 3.0. Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, editors. W3C Working Draft, 13 December 2011. XSL Transformations (XSLT) Version 3.0. Michael Kay, editor. W3C Working Draft, 10 July 2012. XQuery 3.0: An XML Query Language. Jonathan Robie, Don Chamberlin, Michael Dyck, John Snelson, editors. W3C Working Draft, 13 December 2011. XPath and XQuery Functions and Operators 3.0. Michael Kay, editor. W3C Working Draft, 13 December 2011. XQuery and XPath Data Model 3.0. Norman Walsh, Anders Berglund, John Snelson, editors. W3C Working Draft, 13 December 2011. 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. John Boyer, Merlin Hughes, Joseph Reagle, authors/editors. W3C Recommendation, 08 November 2002. RFC 1321: The MD5 Message-Digest Algorithm. Ronald L. Rivest, editor. Network Working Group. April 1992. Secure Hash Standard. U.S. Department Of Commerce, National Institute of Standards and Technology. 1995 April 17. Digital Signature Standard (DSS). U.S. Department Of Commerce, National Institute of Standards and Technology. 1994 May 19. RFC 1750: Randomness Recommendations for Security. D. Eastlake, 3rd, S. Crocker, J. Schiller, editors. Network Working Group. December 1994. RFC 3852: Cryptographic Message Syntax (CMS). R. Housley, editor. Network Working Group. July 2004. RFC 5958: Asymmetric Key Packages. S. Turner, editor. Internet Engineering Task Force (IETF). August 2010. RFC 5959: Algorithms for Asymmetric Key Package Content Type. S. Turner, editor. Internet Engineering Task Force (IETF). August 2010. RFC 2104: HMAC: Keyed-Hashing for Message Authentication. H. Krawczyk, M. Bellare, R. Canetti, editors. Network Working Group. February, 1997. 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. Summary of Error Conditions The canonicalization algorithm is not supported. The digest algorithm is not supported. The signature algorithm is not supported. I/O error while reading keystore, or the password is incorrect. Permission denied to read keystore. The keystore URL is invalid. The keystore type is not supported. Cannot find key for alias in given keystore. Cannot find Signature element. No such padding. Incorrect padding. The encryption type is not supported. The secret key is invalid. Illegal block size. The algorithm or transformation is not supported. The decryption type is not supported. The provider is not set. The output format is not supported.