Difference between revisions of "Cryptographic Module"
m (→XML Signature) |
|||
Line 162: | Line 162: | ||
|- | |- | ||
| valign='top' | '''Summary''' | | valign='top' | '''Summary''' | ||
− | |<code>$canonicalization-algorithm</code> must either be <code>inclusive-with-comments</code>, <code>inclusive</code>, <code>exclusive-with-comments</code> or <code>exclusive</code>. If not specified, the default value is <code>inclusive-with-comments</code>.<br/> | + | |<code>$canonicalization-algorithm</code> must either be <code>inclusive-with-comments</code>, <code>inclusive</code>, <code>exclusive-with-comments</code> or <code>exclusive</code>. If not specified, the <b>default value is <code>inclusive-with-comments</code><b/>.<br/> |
<code>$digest-algorithm</code> must be one of the following: <code>SHA1</code>, <code>SHA256</code> or <code>SHA512</code>. Default is <code>SHA1</code>.<br/> | <code>$digest-algorithm</code> must be one of the following: <code>SHA1</code>, <code>SHA256</code> or <code>SHA512</code>. Default is <code>SHA1</code>.<br/> | ||
<code>$signature-algorithm</code> must either be <code>RSA_SHA1</code> or <code>DSA_SHA1</code>. The default is <code>RSA_SHA1</code>.<br/> | <code>$signature-algorithm</code> must either be <code>RSA_SHA1</code> or <code>DSA_SHA1</code>. The default is <code>RSA_SHA1</code>.<br/> |
Revision as of 11:14, 11 October 2011
This module contains XQuery functions to perform cryptographic operations in XQuery. The cryptographic module is based on an early draft of the EXPath Cryptographic Module and provides the following functionality:
- Creation of message authentication codes (HMAC)
- Encryption and decryption
- Creation and validation of an XML Digital Signature
This module is introduced with Version 7.0 of BaseX.
Contents
Message Authentication Code (MAC)
crypto:hmac
Signatures | crypto:hmac($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string()) as xs:string() crypto:hmac($message as xs:string(), $secret-key as xs:string(), algorithm as xs:string(), $encoding as xs:string()) as xs:string()
|
Summary | Creates a message authentication code via a cryptographic hash function and a secret key. $encoding must either be hex , base64 or the empty string (default is base64 ) and specifies the encoding of the returned authentication code.$algorithm describes the hash algorithm which is used for encryption. Currently supported are md5 , sha1 , sha256 , sha384 , sha512 .
|
Errors | FOCX0013 is raised if the specified hashing algorithm is not supported. FOCX0014 is raised if the specified encoding method is not supported. |
Example | Returns the message authentication code (MAC) for a given string.
Query: crypto:hmac('message','secretkey','md5','base64') Result: 34D1E3818B347252A75A4F6D747B21C2 |
Encryption & Decryption
The encryption and decryption functions underlie several limitations:
- Cryptographic algorithms are limited to
symmetric
algorithms only. This means that the same secret key is used for encryption and decryption. - Available algorithms are
DES
andAES
. - The result of an encryption using the same message, algorithm and key looks different each time it is executed. This is due to a random initialization vector which is appended to the message and simply increases security.
- Padding is fixed to
PKCS5Padding
.
crypto:encrypt
Signatures | crypto:encrypt($input as xs:string(), $encryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()
|
Summary | Encrypts the given input string.
|
Errors | FOCX0016 is raised if padding problems arise. FOCX0017 is raised if padding is incorrect. |
Example | Encrypts input data.
Query: crypto:encrypt('message', 'symmetric','keykeyke','DES') |
crypto:decrypt
Signatures | crypto:decrypt($input as xs:string(), $decryption-type as xs:string(), $secret-key as xs:string(), $cryptographic-algorithm as xs:string()) as xs:string()
|
Summary | Decrypts the encrypted $input .
|
Errors | FOCX0016 is raised if padding problems arise. FOCX0017 is raised if padding is incorrect. |
Example | Decrypts input data and returns the original string.
Query: let $encrypted := crypto:encrypt('message', 'symmetric','keykeyke','DES') return crypto:decrypt($encrypted, 'symmetric','keykeyke','DES') Result: message |
XML Signature
XML Signatures are used to sign data. In our case, the data which is signed is an XQuery node. The following example shows the basic structure of an XML signature.
XML Signature
<Signature> <SignedInfo> <CanonicalizationMethod/> <SignatureMethod/> <Reference> <Transforms/> <DigestMethod/> <DigestValue/> </Reference> <Reference/> </SignedInfo> <SignatureValue/> <KeyInfo/> <Object/> </Signature>
- SignedInfo contains or references the signed data and list algorithm information
- Reference specifies the signed node
- Transforms caontains transformations (i.e. XPath expressions) that are applied to the input node in order to sign a subset
- DigestValue holds digest value of the transformed references
- SignatureValue contains the Base64 encoded value of the encrypted digest of the
SignedInfo
element - KeyInfo provides information on the key that is used to validate the signature
- Object contains the node which is signed if the signature is of type
enveloping
Signature Types
Depending on the signature type, the signature
element is either placed as a child of the signed node (enveloped
type), or directly contains the signed node (enveloping
type). Detached
signatures are so far not supported.
Digital Certificate
The generate-signature
function allows to pass a digital certificate
. This certificate holds parameters that allow to access key information stored in a Java key store which is then used to sign the input document. Passing a digital certificate
simply helps re-using the same key pair to sign and validate data. The digital certificate
is passed as a node and has the following form:
<digital-certificate> <keystore-type>...</keystore-type> <keystore-password>...</keystore-password> <key-alias>...</key-alias> <private-key-password>...</private-key-password> <keystore-uri>...</keystore-uri> </digital-certificate>
crypto:generate-signature
Signatures | crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $digital-certificate as node()) as node() crypto:generate-signature($input-doc node(), $canonicalization-algorithm as xs:string(), $digest-algorithm as xs:string(), $signature-algorithm as xs:string(), $signature-namespace-prefix as xs:string(), $signature-type as xs:string(), $xpath-expression as xs:string(), $digital-certificate as node()) as node()
|
Summary | $canonicalization-algorithm must either be inclusive-with-comments , inclusive , exclusive-with-comments or exclusive . If not specified, the default value is inclusive-with-comments .
|
Errors | FOCX0001 is raised if the canonicalization algorithm is not supported. FOCX0002 is raised if the digest algorithm is not supported. |
Example | Generates an XML Signature.
Query: crypto:generate-signature(<a/>, '', '', '', '', '') Result: <a> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> <Reference URI=""> <Transforms> <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> <DigestValue>9hvH4qztnIYgYfJDRLnEMPJdoaY=</DigestValue> </Reference> </SignedInfo> <SignatureValue>Pn/Jr44WBcdARff2UVYEiwYW1563XdqnU87nusAIaHgzd+U3SrjVJhPFLDe0DJfxVtYzLFaznTYE P3ddeoFmyA==</SignatureValue> <KeyInfo> <KeyValue> <RSAKeyValue> <Modulus>rtvpFSbCIE2BJePlVYLIRIjXl0R7ESr2+D+JOVKn7AM7VZbcbRDPeqRbjSkEz1HWC/N067tjB3qH 4/4PPT9bGQ==</Modulus> <Exponent>AQAB</Exponent> </RSAKeyValue> </KeyValue> </KeyInfo> </Signature> </a> |
crypto:validate-signature
Signatures | crypto:validate-signature($input-doc as node()) as xs:boolean()
|
Summary | Checks if the given node contains a Signature element and whether the signature is valid. In this case true is returned. If the signature is invalid the function returns false .
|
Errors | FOCX0015 is raised if the signature element cannot be found. FOCX9994 is raised if an unspecified problem occurs during validation. |
Example | Validates an XML Signature. |