Cryptographic Module

This document defines a set of [[xpath-30]] extension functions to perform cryptographic operations. These functions are related to XML Digital Signature, to encryption and decryption, and to hashing and digesting of messages. They have been designed to be compatible with [[xquery-30]] and [[xslt-30]], as well as any other standard based on [[xpath-30]].

The functions are defined on the datatypes defined in [[xmlschema-2]] and [[xpath-datamodel-30]]. Also, the functions are defined on nodes and node sequences as defined in the [[xpath-datamodel-30]] and are following the good practices inferred from [[xpath-functions-30]].

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 xs:string.

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

crypto:hash($data     as xs:anyAtomicType,
	     $algorithm as xs:string,
	     $encoding 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 [=crypto:unknown-algorithm=]. The supported algorithms are implementation dependent.
$encoding is the encoding of the output. The legal values are \"hex\" and "base64". The default value is "base64".

The `crypto:hmac` function

HMAC (Keyed-Hashing for Message Authentication) [[rfc2104]] is a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function 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 has two signatures; the first one outputs the result as xs:byte*, while the second one outputs the result as encoded xs:string.

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

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

$data is the data to be authenticated. This parameter can be of type xs:string, xs:byte*, 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:byte*, xs:base64Binary, or xs:hexBinary.
$algorithm is the cryptographic hashing algorithm. If it is specified an unsupported algorithm, this is an error [=crypto:unknown-algorithm=]. The supported algorithms are implementation dependent.
$encoding is the encoding of the output. The legal values are "hex" and "base64". The result is generated accordingly, as xs:base64Binary string or xs:hexBinary string.

XML Digital Signature

A digital signature is a technique to certify that a digital document is authentic. This means that the origin of the document is known and there is the ability to identify if the digital document has been changed since the digital signature was applied to it. This is done by means of a cryptographic transformation.

This function can apply an XML digital signature to one or more resources. There are three types of XML digital signatures, namely enveloped, enveloping, and detached signatures.

According to [[xmldsig-core]], the enveloped and enveloping signatures are applied to the same digital resource (and XML document), while the detached signatures can be applied to more than one digital resources.

The designation of these digital resources is to be made based upon the explanations given in [[xmldsig-core]].

In order to reference these digital resources, this function is using an XML syntax inspired by [[xmldsig-core]]. For details, see below the parameter $resources.

The `crypto:generate-signature` function

The function has its parameters passed as a map(xs:string, item()). After the function's signature, an example of parameters is given.

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

$data is the data to be signed.
$parameters represent the parameters used for generating the XML digital signature. For details regarding these parameters, see the table and the example below.

Explanations about `$parameters` parameter

Parameters used for generating a XML digital signature
Key (as `xs:string`)	Value	Meaning
`canonicalization-algorithm`	`xs:string`	The canonicalization algorithm applied to the `SignedInfo` element prior to performing signature calculations. Possible values are given in the list below. The default value is "inclusive-with-comments-1.1". If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=]. (Optional) `inclusive-1.1`, identifier `http://www.w3.org/2006/12/xml-c14n11`, for XML 1.1 documents, see [[xmldsig-core]], section 6.5.2 Canonical XML 1.1. `inclusive-with-comments-1.1`, identifier `http://www.w3.org/2006/12/xml-c14n11#WithComments`, for XML 1.1 documents, see [[xmldsig-core]], section 6.5.2 Canonical XML 1.1. `inclusive-1.0`, identifier `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`, for XML 1.0 documents, see [[xmldsig-core]], section 6.5.1 Canonical XML 1.0. `inclusive-with-comments-1.0`, identifier `http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments`, for XML 1.0 documents, see [[xmldsig-core]], section 6.5.1 Canonical XML 1.0. `exclusive`, identifier `http://www.w3.org/2001/10/xml-exc-c14n#`, see [[xml-exc-c14n]], section 4. Use in XML Security. `exclusive-with-comments`, identifier `http://www.w3.org/2001/10/xml-exc-c14n#WithComments`, see [[xml-exc-c14n]], section 4. Use in XML Security.
`digest-algorithm`	`xs:string`	The digest algorithm to be applied to the signed object. Possible values are: "SHA1" (identifier `http://www.w3.org/2000/09/xmldsig#sha1`, see [[xmldsig-core]], section 6.1 Algorithm Identifiers and Implementation Requirements), "SHA256", and "SHA512". The default value is "SHA1". If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=]. (Optional)
`signature-algorithm`	`xs:string`	The algorithm used for signature generation and validation. Possible values are: "DSAwithSHA1" (identifier `http://www.w3.org/2000/09/xmldsig#dsa-sha1`, see [[xmldsig-core]], section 6.1 Algorithm Identifiers and Implementation Requirements), and "RSAwithSHA1" (identifier `http://www.w3.org/2000/09/xmldsig#rsa-sha1`, see [[xmldsig-core]], section 6.1 Algorithm Identifiers and Implementation Requirements). The default value is "DSAwithSHA1". If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=]. (Optional)
`signature-namespace-prefix`	`xs:string`	The namespace prefix for signature. If this parameter is not provided, the default value of 'dsig' will be used. (Optional)
`signature-type`	`xs:string`	The method used for signing the content of signature. Possible values are: "enveloping", "enveloped", and "detached". The default value is "enveloped". If the parameter specifies an unsupported signature type, this is an error [=crypto:signature-type=]. (Optional)
`references`	`element(Reference)*`	The references to the digital resources to be signed. If this parameter is not provided, the whole input document will be signed. If the signature is of `enveloped` or `enveloping` type, and more than one resource is inputted to be signed, this is an error [=crypto:input-resources=]. More details about this parameter can be found at . (Optional)
`key`	`xs:anyAtomicType`	The secret key used for signing. This parameter can be of type `xs:string`, `xs:base64Binary`, or `xs:hexBinary`. If the key is invalid or missing, this is an error [=crypto:invalid-crypto-key=].

Example of `$parameters` parameter

	map {
		"canonicalization-algorithm" := "inclusive-with-comments",
	 	"digest-algorithm" := "SHA1",
	 	"signature-algorithm" := "RSA_SHA1",
	 	"signature-namespace-prefix" := "digsig",
	 	"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>
			)
		"key" :=
			    "-----BEGIN RSA PRIVATE KEY-----
			MIIEowIBAAKCAQEAhPxBGln4YOcOGOxmRYEN8nzYHYvQx+PP8GnbJ+kW4f6HvH8WMAUa2lTB6gib
			LzJGezhqkMy8NT8ogVz8xbra3AyK/IBDzXpWtPhSxVOCo6hJfTjj7wX3E2AVN9CTUOYrS/3iSu1q
			/6MoB6MDIj8wV0HO1ujXqEip45UgVl+xRVtU+1wiJQ7Gc8GEEyHVtK/X4joiyCEebJhFsI42Z9e4
			aETI/XOaLszyEQeipMRlyznpRL2x0chz+yj7KuwiMqBZmPYyeWBsbldW8xREwnHEyko5GWc6wkEi
			vgFwzKaZWo2ct3pmZ9vwXKecAxbeJbyJQl/PDfSnqcwyhL6pOaSAuQIDAQABAoIBAHo5hnR7wIb/
			lbteetjitjjqeY8eU/OD9DfYcu6Jkth/Ia4jd/cGmhmU0O0Sn96O7KyPu5H+OfUOaWIMXt400LZy
			aMON98NA77RAj4KBMI7OO0z2Hrgu2Vlbc+TqtJskESM04ulOsIroIAB02Ip/XSS1fS+UrbEjp9Fd
			3GzGYp2E6IF/YtTXMiqgdrZVAoDPtxiMR/1KXuETiBkeMxPvXfgePXLi/rYBDcecmfsCEzDX8RZV
			xLoPKFxuLaIrzdVhGVHwp88fB57OufLytmuvro71FNrFzcIO88NyDpEQVnsBadm9Ir0mb5uhYq9j
			YV444b2Gra0/onJm7e/zRUSSJGkCgYEA67Q8gBSADrkc0UCypjnFV8WWCQJBPspb9Vnf2MJi5aYM
			U5Sa/2H+tNoY+fJoa/eDSu1jeAn71TDcXZizihj3IT8gVdoXSncbcTulxEnaOi85Q2uKfSia16rX
			d+MufjJ4UDC7vR/Ve+zIQOxpzBmcFO5cMnLS3mJdpWSdS7DyQpMCgYEAkG+6udsQ02GEKaJZl2mi
			XBqe4Rh187sDCwiqSO5ItS4jUg1xF1cn1PuF2nvjztZyEsaKKYdiqekEQv3jA6gRsWFvRi/abFN3
			zau/5M42v7H1cgU7m+FsDywhN5IRAmGfEyL/2wpKuZ6lD2qqhGkXmxqyEqgmEClyIwxJKHWiAwMC
			gYBCJK8Bpj8VYp8SnZxEh1u4uMrUtlxG2ZSasmDdvBbyqPk2jzI7zm0ipT1zDrJ88dVXNmy+Z9bS
			ycZdQZfIfh8DpmpVjUER9YCu8vUeszbZMx1XrRsM6lMhiGC01PzcDx+yKSrV9NP81cKQbYd27gzd
			1tHqmkxQebwbyLNXZU1mnwKBgDpuiPsBbdgmHkJ9pIMFwCJEvrvPmoBEyuFe2wzwIUfy52UdfP/1
			SW73ZlpSPoIB7Vo9Kc3NMJQOaaP0dC+Zgbbh9RNO7q1eQxxYfCRDbJC2nNZI2amhU4b70mBZ3jm5
			ZpJmWV2y1zIqxRnsjBlPLraX4Sx9DBEDw2H8aWhN1oIjAoGBANc0gizRHGfOK2UASXskuO5Ueias
			6z0V7J/m93E7wK8IQHcZXGloy8S9QSX6uAqe48ZDVCZGPxqq7TppT+P9WsdqkXqxR7M/KLa+7Y6C
			s1tkDtD9uOJN6CsLuVjfuo4ZT5SwC7pq842aQrqJveKWKdzEorQjWKeN8OM2wzEMs0P1
			-----END RSA PRIVATE KEY-----"	
	}

Explanations about `$resources` parameter

The `$resources` parameter
Key (as `xs:string`)	Value	Meaning
`Reference`	`element()`	This is the parent element for a reference to a resource to be signed. Its namespace is `http://www.w3.org/2000/09/xmldsig#`. Its `URI` attribute identifies a resource using a URI-Reference (for details see [[xmldsig-core]], section 4.3.3.1 The URI Attribute).
`Transforms`	`element()`	This element contains an ordered list of `Transform` elements.
`Transform`	`element()`	This element describes how the signer obtained the data object that is to be digested. The `Algorithm` attribute's value specifies the name of the algorithm to be applied, and the `Transform` element's text content provides additional data for processing using that algorithm. For more details and schema of this element, see [[xmldsig-core]], section 4.3.3.4 The Transforms Element.
`XPath`	`element()`	The XPath expression to be applied to the input document, in order to get the resource to be signed. The version of XPath to be used is 1.0, plus a function named `here`. The `Filter` attribute's value provides the name of the operation (intersection, subtraction and union) used for combining the XPath-selected subtrees. For more details, see [[xmldsig-core]], section 6.6.3 XPath Filtering, and [[xmldsig-filter2]].

The `crypto:validate-signature` function

This function validates an XML Digital Signature.

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

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

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

$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 to be used for the input data, but this mechanism is not made available by the implementation, this is an error [=crypto:inexistent-padding=]. Also, when the input data is expected to have a particular padding mechanism, but the data is not padded accordingly to this mechanism, this is an error [=crypto:incorrect-padding=].
$type is the type of encryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error [=crypto:encryption-type=].
$parameters represents the parameters needed for the current operation. More details about this parameter can be found at .

Explanations about `$parameters` parameter

The `$parameters` parameter of `crypto:encrypt`
Key (as `xs:string`)	Value	Meaning
`key`	`xs:anyAtomicType`	This 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 or missing, this is an error [=crypto:invalid-crypto-key=]. If the length of data provided to the block cipher is incorrect, this is an error [=crypto:block-size=].
`algorithm`	`xs:string`	This 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 or the parameter is missing, this is an error [=crypto:unknown-algorithm=]. The supported algorithms are implementation dependent.
`iv`	`xs:string`	This is the initialization vector for symmetric encryption. If the initialization vector is missing or it is not as it is requested by the encryption algorithm, this is an error [=crypto:incorrect-initialization-vector=]. For asymmetric encryption, this parameter is not needed.

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

$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 to be used for the input data, but this mechanism is not made available by the implementation, this is an error [=crypto:inexistent-padding=]. Also, when the input data is expected to have a particular padding mechanism, but the data is not padded accordingly to this mechanism, this is an error [=crypto:incorrect-padding=].
$type is the type of decryption. Legal values: "symmetric", and "asymmetric". If the parameter has an illegal value, this is an error [=crypto:decryption-type=].
$parameters represents the parameters needed for the current operation. More details about this parameter can be found at .

Explanations about `$parameters` parameter

The `$parameters` parameter of `crypto:decrypt`
Key (as `xs:string`)	Value	Meaning
`key`	`xs:anyAtomicType`	This 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 or missing, this is an error [=crypto:invalid-crypto-key=]. If the length of data provided to the block cipher is incorrect, this is an error [=crypto:block-size=].
`algorithm`	`xs:string`	This 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 or the parameter is missing, this is an error [=crypto:unknown-algorithm=]. The supported algorithms are implementation dependent.
`iv`	`xs:string`	This is the initialization vector for symmetric decryption. If the initialization vector is missing or it is not as it is requested by the decryption algorithm, this is an error [=crypto:incorrect-initialization-vector=]. For asymmetric decryption, this parameter is not needed.

Status of this document

Introduction

Namespace conventions

Error management

Integrity and Authentication of Data

The `crypto:hash` function

The `crypto:hmac` function

XML Digital Signature

The `crypto:generate-signature` function

Explanations about `$parameters` parameter

Example of `$parameters` parameter

Explanations about `$resources` parameter

The `crypto:validate-signature` function

Encryption and Decryption

The `crypto:encrypt` function

Explanations about `$parameters` parameter

The `crypto:decrypt` function

Explanations about `$parameters` parameter

Scenarios of usage

Generation of OAuth signature

Generation of AWS Signature Version 4 signature

Generation of enveloped digital XML signature of a document

Summary of Error Conditions

Status of this document

Introduction

Namespace conventions

Error management

Integrity and Authentication of Data

The crypto:hash function

The crypto:hmac function

XML Digital Signature

The crypto:generate-signature function

Explanations about $parameters parameter

Example of $parameters parameter

Explanations about $resources parameter

The crypto:validate-signature function

Encryption and Decryption

The crypto:encrypt function

Explanations about $parameters parameter

The crypto:decrypt function

Explanations about $parameters parameter

Scenarios of usage

Generation of OAuth signature

Generation of AWS Signature Version 4 signature

Generation of enveloped digital XML signature of a document

Summary of Error Conditions

The `crypto:hash` function

The `crypto:hmac` function

The `crypto:generate-signature` function

Explanations about `$parameters` parameter

Example of `$parameters` parameter

Explanations about `$resources` parameter

The `crypto:validate-signature` function

The `crypto:encrypt` function

Explanations about `$parameters` parameter

The `crypto:decrypt` function

Explanations about `$parameters` parameter