view release on metacpan or  search on metacpan

lib/XML/LibXML/xmlsec.pm  view on Meta::CPAN

=head1 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.


=head2 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.

=head1 METHODS

=head2 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. 

=head2 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().

=head2 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
I<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

=head2 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 L<LibXML::Document|https://metacpan.org/pod/distribution/XML-LibXML/lib/XML/LibXML/Document.pod>
already setup with the algorithm identifiers and the signature placeholder.

The options are as follows

=over 1

=item id => 'mydoc' indicates the id of the xml element subject of the signature

=item start => <libxml node> indicates a starting Signature o dsig:Signature of the signing process

=item id-attr => 'ID' indicates the name of the id attribute applied. Default lowercase 'id'

=item id-node => 'mytagname' indicates the tag name of the xml element subject of the signature

=back 

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

=head2 $signer->verifydoc($xmldoc, %options);

verifydoc will verify an already signed xmldoc. Options are alike the signdoc method.
Will return 1 if verification is correct.

=head2 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.

=head2 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
B<Please beware that any private key will be dumped unencrypted>
The options, as stated in xmlsec documentation are as follows:

=over 1

=item B<xmlSecKeyDataTypeUnknown> The key data type is unknown (same as xmlSecKeyDataTypeNone).

=item B<xmlSecKeyDataTypeNone> The key data type is unknown (same as xmlSecKeyDataTypeUnknown).

=item B<xmlSecKeyDataTypePublic> The key data contain a public key.

=item B<xmlSecKeyDataTypePrivate> The key data contain a private key.

=item B<xmlSecKeyDataTypeSymmetric> The key data contain a symmetric key.

=item B<xmlSecKeyDataTypeSession> The key data contain session key (one time key, n

=item B<xmlSecKeyDataTypePermanent> The key data contain permanent key (stored in keys manager).

=item B<xmlSecKeyDataTypeTrusted> The key data is trusted.

=item B<xmlSecKeyDataTypeAny> Any key data.

=back

=head2 loadkeys('store.xml')

This will restore a previously saved keys

=head1 LIMITATIONS AND TODO LIST

This module exposes only a subset of the xmlsec library features.
As it is

=over 4

=item *

Only signature and verification is available. Document encryption is on the TODO list

=item *

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.

=item *

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.

=back

=head1 SEE ALSO

See L<W3C XML signature definition|https://www.w3.org/TR/xmldsig-core/>.
See L<W3C XML encryption definition|https://www.w3.org/TR/xmlenc-core/>.
The original xmlsec library has a webpage at L<https://www.aleksey.com/xmlsec/>

=head1 AUTHOR

Erich Strelow, E<lt>hstrelo@puc.clE<gt>

=head1 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.


=cut