NAME
XML::LibXML::xmlsec - XML signing/encription using xmlsec library
SYNOPSIS
use XML::LibXML::xmlsec;
my $signer=XML::LibXML::xmlsec->new();
$signer->loadpkey(PEM => 'jdoe.pem', secret => 'hush');
$signer->template4sign($xmldoc,'rsa-sha1','MyDocument');
$signer->signdoc($xmldoc);
unless( $signer->verify($received_xml)) {
die "This document was tampered";
}DESCRIPTION
XML::LibXML::xmlsec is a bind module for xmlsec, a C library aimed for XML digital signature and encryption as described in W3C standards.
INSTALLATION
You must have a running xmlsec library, which in turns has several dependencies. There are xmlsec binaries built into many Linux distributions, as well as binaries for Windows available.
METHODS
loadpkey
$signer->loadpkey(PEM => 'me.pem', secret => 'mypassword');
$signer->loadpkey(DER => 'me.pem', name => 'joe');
$signer->loadpkey(PEM => $string_with_pem);loadpkey will set the private key needed for digital signature. The key may be passed as a filename value, or it might be the key itself as a string. A PEM=>val pair indicates PEM format, DER=>val indicates DER format and PFX=>val indicates PKCS12 format. An optional secret value will be used to decrypt the key. An optional name argument will be used to mention the private key in further methods. Returns 0 on success.
loadcert
$signer->loadcert(PEM => 'me.crt', secret => 'hush')
$signer->loadcert(PEM => 'joe.crt', name => 'joe')loadcert will set the X509 certificate needed for verifying or digital signature. The value may be passed in similar fashion as in loadpkey().
template4sign($doc,'rsa-sha256',$id)
Adds a signature template branch to the LibXML $doc for the signature of the $id element. The second argument is a case insensitive string that identifies the algorithm combination keying-digest in order to setup the template. The algorithm must be one supported by the xmlsec library and corresponds to the SignatureMethod definition. Some of the known supported algorithms: RSA-SHA1, RSA-SHA224, RSA-SHA256, RSA-SHA384, RSA-SHA512, DSA-SHA256, ECDSA-SHA25. Returns the modified xml document
signdoc
$signer->signdoc($xmldoc, %options);signdoc will compute the digital signature and then add it as contents to the XML document. The argument is expected to be a signature envelope as a well behaved LibXML::Document already setup with the algorithm identifiers and the signature placeholder.
The options are as follows
- id => 'mydoc' indicates the id of the xml element subject of the signature
- start => <libxml node> indicates a starting Signature o dsig:Signature of the signing process
- id-attr => 'ID' indicates the name of the id attribute applied. Default lowercase 'id'
- id-node => 'mytagname' indicates the tag name of the xml element subject of the signature
id-attr and id-node are provided as tweaks in order to be able to sign a DTD-less documents in the same way the option --id-attr works in xmlsec1 utility
$signer->verifydoc($xmldoc, %options);
verifydoc will verify an already signed xmldoc. Options are alike the signdoc method. Will return 1 if verification is correct.
lastmsg
lastmsg will show the last error or warning message that might come out from the xmlsec engine. Particularly the verifydoc will set this message so there's a hint on the reason for a document to fail validation.
savekeys('store.xml',XML::LibXML::xmlsec::xmlSecKeyDataTypeAny)
This will dump the current contents of the previously loaded keys in the named file. The second argument is a bitmask indicating which keys will be dumped. The file can be used in the future with loadkeys Please beware that any private key will be dumped unencrypted The options, as stated in xmlsec documentation are as follows:
- xmlSecKeyDataTypeUnknown The key data type is unknown (same as xmlSecKeyDataTypeNone).
- xmlSecKeyDataTypeNone The key data type is unknown (same as xmlSecKeyDataTypeUnknown).
- xmlSecKeyDataTypePublic The key data contain a public key.
- xmlSecKeyDataTypePrivate The key data contain a private key.
- xmlSecKeyDataTypeSymmetric The key data contain a symmetric key.
- xmlSecKeyDataTypeSession The key data contain session key (one time key, n
- xmlSecKeyDataTypePermanent The key data contain permanent key (stored in keys manager).
- xmlSecKeyDataTypeTrusted The key data is trusted.
- xmlSecKeyDataTypeAny Any key data.
loadkeys('store.xml')
This will restore a previously saved keys
LIMITATIONS AND TODO LIST
This module exposes only a subset of the xmlsec library features. As it is
Only signature and verification is available. Document encryption is on the TODO list
xmlsec can use several crypto engines. This perl module uses only the default compiled-in crypto engine. Anyway, this is the reason why this module doesn't interact with any Crypt or OpenSSL perl module.
xmlsec has a strong libxml2 binding. This module will accept XML::LibXML handles, but in turn will do processing in the underlying xmlsec/libxml2 C libraries.
SEE ALSO
See W3C XML signature definition. See W3C XML encryption definition. The original xmlsec library has a webpage at https://www.aleksey.com/xmlsec/
AUTHOR
Erich Strelow, <hstrelo@puc.cl>
COPYRIGHT AND LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.3 or, at your option, any later version of Perl 5 you may have available.