Copyright © 2012-2013 Claudius Teodorescu, published by the
This specification was published by the
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...
revisiondesc
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 check the integrity and authentication of the data.
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 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).
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 Service QName | Cryptographic Service Description |
---|---|
crypto:hash | See |
crypto:hmac | See |
crypto:list-providers
function
This function lists the available cryptographic providers.
crypto:providers-list
element
The crypto:providers-list
element represents the list of the available cryptographic providers:
crypto:provider
element
The crypto:provider
element contains the name of an available cryptographic provider:
crypto:list-services
function
This function lists the cryptographic services a provider provides.
$provider-name
is the provider's name. TBD: case when provider is not registered, etc.
crypto:services-list
element
The crypto:services-list
element represents the list of the available cryptographic services for a provider:
crypto:service
element
The crypto:service
element contains details about an available cryptographic service:
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.
$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
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.
$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
TBD.
crypto:generate-key-pair
function
This function generates a new pair of public and private cryptographic keys, to be used with a specific cryptographic algorithm.
crypto:generate-secret-key
function
This function generates a new secret key, to be used with a specific cryptographic algorithm.
crypto:compare-keys
function
crypto:key-agrement
function
crypto:convert-key-specification-to-key-object, crypto:convert-key-object-to-key-specification
function
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.
crypto:generate-signature
function
The function has its parameters passed as a $references
parameter is inspired by
Example of parameters:
$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'. If the parameter specifies an unsupported signature type, this is an error
$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
crypto:validate-signature
function
This function validates an XML Digital Signature.
$data
is the enveloped, enveloping, or detached signature. If
the Signature element cannot be found, this is an error
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.
crypto:encrypt
function
This function encrypts data.
$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
$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
algorithm
as
iv
as
provider
as
crypto:decrypt
function
This function decrypts data.
$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
$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
algorithm
as
iv
as
provider
as
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.
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.
$store-format
is the format of the secure store.
$store-password
is the password for the secure store.
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.
$secure-store
is the secure store.
$store-password
is the password for the secure store.
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.
$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.
crypto:get-secure-store-metadata
function
This function gets metadata for a secure store. It returns a crypto:metadata element.
$secure-store-handle
is the secure store handle.
crypto:metadata
element
The crypto:metadata
element contains metadata about a resource.
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.
crypto:add-entry
function
This function adds an entry to a secure store. It returns true if successfully completed, false if not.
$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.
crypto:get-entry
function
This function gets an entry from a secure store. It returns the entry.
$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.
crypto:delete-entry
function
This function delets an entry from a secure store. It returns true if successfully completed, false if not.
$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.
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.
$secure-store-handle
is the secure store handle.
$alias
is the alias for the data to be stored.
crypto:metadata
element
The crypto:metadata
element contains metadata about a resource.
creation-date
is the entry's creation date.
type
is the entry's type.
crypto:list-trusted-certificate-authorities
function
This function lists the most-trusted certificate authorities in a secure store.
TBD.
crypto:generate-certificate
function
This function generates a digital certificate.
crypto:validate-certificate
function
This function validates a digital certificate.
crypto:parse-certificate
function
This function parses a digital certificate.
crypto:generate-certification-path
function
This function validates the certification path for a digital certificate.
crypto:validate-certification-path
function
This function validates the certification path for a digital certificate.
crypto:generate-certification-request
function
This function generates a certificate signing request, in order to apply for a digital identity certificate, which is to be issued by a Certificate Authority .
crypto:validate-certification-request
function
This function validates a certificate signing request.
crypto:validate-certificate-revocation-list
function
This function validates a certificate revocation list.
TBD.
TBD.
crypto:generate-random-number
function
This function generates a random number that is cryptographically strong.
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.
provider
option
Represents the provider for the current operation. If the provider does not exist, this is an error
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
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
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
signature-namespace-prefix
option
This option represents the namespace prefix for signature.