This proposal defines a set of XPath 2.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 1.0 and XSLT 2.0, as well as any other standard based on XPath 2.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 ensure the integrity of the data.
This proposal defines a set of XPath 2.0 extension functions to perform these 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 1.0 and XSLT 2.0, as well as any other standard based on XPath 2.0.
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 namespace http://expath.org/ns/error
. In
this document, the err
prefix, when used, is bound to this namespace
URI.
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).
HMAC 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.
crypto:hmac
function
This function generates a message authentication code, based on the input message, by using a cryptographic algorithm and a secret key.
$message
is the message to be authenticated.
$secret-key
is the secret key used for calculating the
authentication code.
$algorithm
is the cryptographic hashing algorithm. If the
parameter specifies an unsupported algorithm, this is an error
$encoding
is the method used for encoding of the authentication
code. Default value: "base64". If the parameter specifies an unsupported
method, this is an error
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
This function has four signatures, as one have to consider that some applications require the ability to specify a subset of a given XML document as the information content to be signed (this is done by using XPath to indicate the subset), and also the ability to use a digital certificate to obtain the key pair, instead of an auto-generated key pair.
The first signature considers the case of auto-generated key pair, and signature for the whole document.
The second signature considers the case of auto-generated key pair, and signature for a subset of the document.
The third signature considers the case of key pair generated from an digital certificate, and signature for the whole document.
The fourth signature considers the case of key pair generated from an digital certificate, and signature for a subset of the document.
$input-doc
is the document 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'.
$xpath-expression
is the XPath expression used for selecting the
subset to be signed. If the XPath expression is invalid, this is an error
$digital-certificate
is the digital certificate to be used for
signing the input document or document subset. The structure of this parameter
is as follows (this is an example):
The following errors can be raised relative to the structure and content of
$digital-certificate parameter:
crypto:validate-signature
function
This function validates an XML Digital Signature.
$input-doc
is the enveloped, enveloping, or detached signature. If
the Signature element cannot be found, this is an error
crypto:generate-self-signed-certificate
function
This function generates, for development purposes, a self signed digital certificate. TODO: To be developed, if such function is of any use.
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 an input string.
$input-string
is the string to be encrypted. When a particular
padding mechanism is requested, but is not available, this is an error
$encryption-type
is the type of encryption. Legal values:
"symmetric", and "asymmetric". If the parameter has an illegal value, this is
an error
$secret-key
is the secret key used for encryption, as string. If
the key is invalid, this is an error
$cryptographic-algorithm
is the cryptographic algorithm used for
encryption. If the parameter specifies an unsupported algorithm, this is an
error
crypto:decrypt
function
This function decrypts an input string.
$input-string
is the string to be decrypted. When a particular
padding mechanism is requested, but is not available, this is an error
$encryption-type
is the type of encryption. Legal values:
"symmetric", and "asymmetric". If the parameter has an illegal value, this is
an error
$secret-key
is the secret key used for encryption, as string. If
the key is invalid, this is an error
$cryptographic-algorithm
is the cryptographic algorithm used for
encryption. If the parameter specifies an unsupported algorithm, this is an
error