Cryptographic Module

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.

Cryptographic Service Providers

Cryptographic providers provide cryptographic services, involving cryptographic operations (encryption, digital signatures, message digests, message authentication), generators and converters of cryptographic material and cryptographic objects (keystores or certificates) containing the cryptographic data. They can be implemented using software, hardware, or both.

Cryptographic services described by this specification
Cryptographic Service QName	Cryptographic Service Description
crypto:hash	See .
crypto:hmac	See .

The `crypto:list-providers` function

This function lists the available cryptographic providers.

crypto:list-providers() as element(crypto:provider-list)

The `crypto:providers-list` element

The crypto:providers-list element represents the list of the available cryptographic providers:

<crypto:providers-list>
    (crypto:provider*)
</crypto:providers-list>

The `crypto:provider` element

The crypto:provider element contains the name of an available cryptographic provider:

<crypto:provider name = xs:string
    version = xs:string>
</crypto:provider>

The `crypto:list-services` function

This function lists the cryptographic services a provider provides.

crypto:list-services($provider-name as xs:string) as element(crypto:service-list)

$provider-name is the provider's name. TBD: case when provider is not registered, etc.

The `crypto:services-list` element

The crypto:services-list element represents the list of the available cryptographic services for a provider:

<crypto:services-list>
    (crypto:service*)
</crypto:services-list>

The `crypto:service` element

The crypto:service element contains details about an available cryptographic service:

<crypto:service qname = xsd:QName
    algorithm? = xs:string
    type? = xs:string
    format? = xs:string?/>

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 [=crypto:unknown-algorithm=].
$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 [=crypto:output-format=].

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 [=crypto:unknown-algorithm=].
$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 [=crypto:output-format=].

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 [[xmldsig-core]].

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 [=crypto:unknown-algorithm=].
$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 [=crypto:unknown-algorithm=].
$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 [=crypto:unknown-algorithm=].
$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'. If the parameter specifies an unsupported signature type, this is an error [=crypto:signature-type=].
$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 [=crypto:keystore-type=].
- keystore-password is the keystore's password. If the keystore cannot be loaded or the password is incorrect, this is an error [=crypto:unreadable-keystore=].
- key-alias is the alias for the key pair used for signing. If no key pair exists for this alias, this is an error [=crypto:alias-key=].
- 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 [=crypto:keystore-url=]. If the user has no acces to the keystore, this is an error [=crypto:denied-keystore=].

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 [=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: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 [=crypto:inexistent-padding=]. Also, when a particular padding mechanism is expected, but the data is not padded properly, 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. 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 [=crypto:secret-key=]. If the length of data provided to the block cipher is incorrect, this is an error [=crypto:block-size=].
- 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 [=crypto:unknown-algorithm=].
- 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 [=crypto:no-provider=].

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 [=crypto:inexistent-padding=]. Also, when a particular padding mechanism is expected, but the data is not padded properly, 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. 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 [=crypto:secret-key=]. If the length of data provided to the block cipher is incorrect, this is an error [=crypto:block-size=].
- 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 [=crypto:unknown-algorithm=].
- 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 [=crypto:no-provider=].

Secure Storing of Sensitive Keying and Data Material

A secure storage is a collection of CRLs, cryptographic keys, cryptographic certificates, cryptographic certificate chains, various secrets, and extensions. It may have different implementation, according to different cryptographic providers. Every entry has a unique alias name and can be protected by its own password.

The `crypto:create-secure-store` function

This function creates a secure store. It returns the store as xs:base64binary if successfully completed, empty sequence if not.

crypto:create-secure-store($store-format as xs:string,
               $store-password as xs:string) as xs:base64binary

$store-format is the format of the secure store.
$store-password is the password for the secure store.

The `crypto:load-secure-store` function

This function loads a secure store in order to operate against it. It returns an xs:long representing the secure store handle.

crypto:load-secure-store($secure-store as xs:base64binary,
               $store-password as xs:string) as xs:long

$secure-store is the secure store.
$store-password is the password for the secure store.

The `crypto:convert-secure-store` function

This function converts a secure store from one format to another. It returns the converted store as xs:base64binary if successfully completed, empty sequence if not.

crypto:convert-secure-store($input-store as xs:base64binary,
               $input-format as xs:string,
               $output-format as xs:string) as xs:base64binary

$input-store is the secure store to be converted.
$input-format is the format of the input secure store.
$output-format is the format of the output secure store.

The `crypto:get-secure-store-metadata` function

This function gets metadata for a secure store. It returns a crypto:metadata element.

crypto:get-secure-store-metadata($secure-store-handle as xs:long) as element(crypto:metadata)

$secure-store-handle is the secure store handle.

The `crypto:metadata` element

The crypto:metadata element contains metadata about a resource.

<crypto:metadata>
    <crypto:secure-store-type>xs:string</crypto:secure-store-type>
    <crypto:provider>xs:string</crypto:provider>
    <crypto:aliases-list>xs:string</crypto:aliases-list>
    <crypto:size>xs:integer</crypto:size>
</crypto:metadata>

secure-store-type is the type of the secure store.
provider is the provider that generated the secure store.
aliases-list is the list of all the aliases in the secure store.
size is the number of entries in the secure store.

The `crypto:add-entry` function

This function adds an entry to a secure store. It returns true if successfully completed, false if not.

crypto:add-entry($secure-store-handle as xs:long,
               $data as xs:base64binary,
               $alias as xs:string,
               $entry-password as xs:string?) as xs:boolean

$secure-store-handle is the secure store handle.
$data is the data to be stored.
$alias is the alias for the data to be stored.
$entry-password is the password for the entry.

The `crypto:get-entry` function

This function gets an entry from a secure store. It returns the entry.

crypto:get-entry($secure-store-handle as xs:long,
               $alias as xs:string,
               $entry-password as xs:string?) as xs:base64binary

$secure-store-handle is the secure store handle.
$alias is the alias for the data to be stored.
$entry-password is the password for the entry.

The `crypto:delete-entry` function

This function delets an entry from a secure store. It returns true if successfully completed, false if not.

crypto:delete-entry($secure-store-handle as xs:long,
               $alias as xs:string,
               $entry-password as xs:string?) as xs:boolean

$secure-store-handle is the secure store handle.
$alias is the alias for the data to be stored.
$entry-password is the password for the entry.

The `crypto:get-entry-metadata` function

This function gets metadata for a secure store entry. It returns a crypto:metadata element if entry exists, empty sequence if the entry does not exist.

crypto:get-entry-metadata($secure-store-handle as xs:long,
               $alias as xs:string) as element(crypto:metadata)?

$secure-store-handle is the secure store handle.
$alias is the alias for the data to be stored.

The `crypto:metadata` element

The crypto:metadata element contains metadata about a resource.

<crypto:metadata>
    <crypto:creation-date>xs:dateTime</crypto:creation-date>
    <crypto:type>("certificate" | "key" | "other")</crypto:provider>
</crypto:metadata>

creation-date is the entry's creation date.
type is the entry's type.

The `crypto:list-trusted-certificate-authorities` function

This function lists the most-trusted certificate authorities in a secure store.

The `crypto:options` element

The crypto:options element represents the options needed for the functions included in this module. Users will specify for a certain functions only the options mentioned in function's description above. In case a needed option is not mentioned for a function, its default value will be used.

<crypto:options>
    <crypto:option name = xs:string value? = xs:string>
        any*
    </crypto:option> *
</crypto:options> ?

The `provider` option

Represents the provider for the current operation. If the provider does not exist, this is an error [=crypto:no-provider=].

<crypto:option name = "provider"
    value = xs:string/>

The `canonicalization-algorithm` option

This option represents the canonicalization algorithm applied to the SignedInfo element prior to performing signature calculations. The default value is "inclusive-with-comments". If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=].

<crypto:option name = "canonicalization-algorithm"
    value = "exclusive" | "exclusive-with-comments" | "inclusive" | "inclusive-with-comments" /> ?

The `digest-algorithm` option

This option represents the digest algorithm to be applied to the signed object. If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=].

<crypto:option name = "digest-algorithm" value = xs:string />

The `signature-algorithm` option

This option represents the algorithm used for signature generation and validation. If the parameter specifies an unsupported algorithm, this is an error [=crypto:unknown-algorithm=].

<crypto:option name = "signature-algorithm" value = xs:string />

The `signature-namespace-prefix` option

This option represents the namespace prefix for signature.

<crypto:option name = "signature-namespace-prefix" value = xs:string />

Introduction

Namespace conventions

Error management

Cryptographic Service Providers

The crypto:list-providers function

The crypto:providers-list element

The crypto:provider element

The crypto:list-services function

The crypto:services-list element

The crypto:service element

Integrity and Authentication of Data

The crypto:hash function

The crypto:hmac function

Key Management

The crypto:generate-key-pair function

The crypto:generate-secret-key function

The crypto:compare-keys function

The crypto:key-agrement function

The crypto:convert-key-specification-to-key-object, crypto:convert-key-object-to-key-specification function

Digital Signature

The crypto:generate-signature function

The crypto:validate-signature function

Encryption and Decryption

The crypto:encrypt function

The crypto:decrypt function

Secure Storing of Sensitive Keying and Data Material

The crypto:create-secure-store function

The crypto:load-secure-store function

The crypto:convert-secure-store function

The crypto:get-secure-store-metadata function

The crypto:metadata element

The crypto:add-entry function

The crypto:get-entry function

The crypto:delete-entry function

The crypto:get-entry-metadata function

The crypto:metadata element

The crypto:list-trusted-certificate-authorities function

Digital Certificates

The crypto:generate-certificate function

The crypto:validate-certificate function

The crypto:parse-certificate function

The crypto:generate-certification-path function

The crypto:validate-certification-path function

The crypto:generate-certification-request function

The crypto:validate-certification-request function

The crypto:validate-certificate-revocation-list function

Cryptographic Hardware

Random Sequences Generation

The crypto:generate-random-number function

The crypto:options element

The provider option

The canonicalization-algorithm option

The digest-algorithm option

The signature-algorithm option

The signature-namespace-prefix option

Summary of Error Conditions

The `crypto:list-providers` function

The `crypto:providers-list` element

The `crypto:provider` element

The `crypto:list-services` function

The `crypto:services-list` element

The `crypto:service` element

The `crypto:hash` function

The `crypto:hmac` function

The `crypto:generate-key-pair` function

The `crypto:generate-secret-key` function

The `crypto:compare-keys` function

The `crypto:key-agrement` function

The `crypto:convert-key-specification-to-key-object, crypto:convert-key-object-to-key-specification` function

The `crypto:generate-signature` function

The `crypto:validate-signature` function

The `crypto:encrypt` function

The `crypto:decrypt` function

The `crypto:create-secure-store` function

The `crypto:load-secure-store` function

The `crypto:convert-secure-store` function

The `crypto:get-secure-store-metadata` function

The `crypto:metadata` element

The `crypto:add-entry` function

The `crypto:get-entry` function

The `crypto:delete-entry` function

The `crypto:get-entry-metadata` function

The `crypto:metadata` element

The `crypto:list-trusted-certificate-authorities` function

The `crypto:generate-certificate` function

The `crypto:validate-certificate` function

The `crypto:parse-certificate` function

The `crypto:generate-certification-path` function

The `crypto:validate-certification-path` function

The `crypto:generate-certification-request` function

The `crypto:validate-certification-request` function

The `crypto:validate-certificate-revocation-list` function

The `crypto:generate-random-number` function

The `crypto:options` element

The `provider` option

The `canonicalization-algorithm` option

The `digest-algorithm` option

The `signature-algorithm` option

The `signature-namespace-prefix` option