This document defines a set of
The functions are defined on the datatypes defined in
Must be ignored, but is required by the schema...
revisiondesc
This document is in an interim draft stage. Comments are welcomed at
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.
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).
crypto:hash
function
This function generates a "message digest" of the input data, by using a cryptographic algorithm. It returns the hash value as
$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
$encoding
is the encoding of the output. The legal values are \"hex\" and "base64". The default value is "base64".
crypto:hmac
function
HMAC (Keyed-Hashing for Message Authentication)
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
$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
$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.
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 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
In order to reference these digital resources, this function is using an XML syntax inspired by $resources
.
crypto:generate-signature
function
The function has its parameters passed as a
$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
$parameters
parameter
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
|
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
|
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 http://www.w3.org/2000/09/xmldsig#rsa-sha1 ,
see |
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 |
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 |
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 |
$parameters
parameter
$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 |
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 |
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 |
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 to be used for the input data, but this mechanism is not made available by the implementation, 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. More details about this parameter can be found at
$parameters
parameter
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 |
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 |
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:decrypt
function
This function decrypts 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 to be used for the input data, but this mechanism is not made available by the implementation, 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. More details about this parameter can be found at
$parameters
parameter
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 |
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 |
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 |