Cryptographic Module

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

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

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

3.2 The crypto:hmac function

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

4.1 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 4.1.1 Explanations about $parameters parameter and the example 4.1.2 Example of $parameters parameter below.

	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-----"	
	}
	

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

5.1 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 5.1.1 Explanations about $parameters parameter.

5.2 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 5.2.1 Explanations about $parameters parameter.

6.1 Generation of OAuth signature

let $signature-base-string :=
	"GET&http%3A%2F%2Fexample.org%2Fresource%26oauth_consumer_key%3Dabcd%26
	oauth_nonce%3DXxFM1VSdB6N%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1449422427%26
	oauth_token%3Dijkl%26oauth_version%3D1.0"
let $key := "dpf43f3p2l4k3l03"
let $signature := return crypto:hmac($signature-base-string, $key, "HMAC-SHA-1")

return $signature				
				

6.2 Generation of AWS Signature Version 4 signature

let $region := "us-east-1"
let $service := 'iam'
let $date-YYYYMMDD := '20120215'
let $s3-secret-key := 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY'
let $kSecret := concat("AWS4", $s3-secret-key)

let $dateKey := crypto:hmac($date-YYYYMMDD, $kSecret, "HMAC-SHA-256")
let $dateRegionKey := crypto:hmac($region, $dateKey, "HMAC-SHA-256")
let $dateRegionServiceKey := crypto:hmac($service, $dateRegionKey, "HMAC-SHA-256")
let $signingKey := crypto:hmac("aws4_request", $dateRegionServiceKey, "HMAC-SHA-256”)

return $signingKey				
				

6.3 Generation of enveloped digital XML signature of a document

let $doc :=
  <data>
    <a>1</a>
    <b>7</b>
    <c />
    <c />
  </data>
let $signature := crypto:generate-signature($doc,
  map {
    "canonicalization-algorithm" := "inclusive-with-comments",
    "digest-algorithm" := "SHA1",
    "signature-algorithm" := "RSA_SHA1",
    "signature-namespace-prefix" := "digsig",
    "signature-type" := "enveloped",
    "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-----"	
  }
)

return $signature