The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
XML-LibXML-xmlsec-0.03
River stage zero No dependents
/ XML::LibXML::xmlsec

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.