XML Digital Signature for PHP
This library was created to sign arbitrary data and whole XML documents using XML digital signatures as per the W3 recommendation using PHP. The code for this class was inspired by the xmlseclibs library, which I found impossible to work with due to its lack of documentation and the fact that the signed documents it produced did not validate properly.
Should this class generate documents that do not validate (as there are many different specs for these signatures, of which I have tested only a handful), please contact me and I will do my best to provide support for your needs.
php composer.phar require "marcelxyz/php-xml-digital-signature"
Alternatively require the
src/XmlDigitalSignature.php file in your project.
Here's a basic overview of how to use this library:
$dsig = new XmlDsig\XmlDigitalSignature(); $dsig->loadPrivateKey('path/to/private/key', 'passphrase'); $dsig->loadPublicKey('path/to/public/key'); $dsig->addObject('I am a data blob.'); $dsig->sign(); $result = $dsig->getSignedDocument();
Please see the
examples/ folder for more elaborate examples.
To sign an XML document you need to answer the following questions:
- Which signature algorithm (RSA/DSA/ECDSA etc.) will you be using?
- Which digest (hashing) method will you be using?
- Which C14N (canonicalization) method will you be using?
- Do you want to include public key information within the resulting XML document?
These are covered in the following subsections.
The following signature algorithms are currently supported:
- DSA (
- RSA (
- Elliptic Curve DSA (
- HMAC (
Specify the appropriate one using the
XmlDsig\XmlDigitalSignature.setCryptoAlgorithm(algo) method with the appropriate
This library currently supports four digest methods, those being:
- SHA1 (
- SHA256 (
- SHA512 (
- RIPMED-160 (
Your version of PHP must provide support for the digest method you choose. This library will check this automatically, but you can also do this yourself by calling PHP's hash_algos() function.
Specify the appropriate digest by calling the
XmlDsig\XmlDigitalSignature.setDigestMethod(digest) method with the appropriate
To add support for a different hashing method (provided your version of PHP supports it), add a new
XmlDsig\XmlDigitalSignature::DIGEST_* const with a value defined in
hash_algos(). Remember to add the proper mapping values to the following class properties:
$digestSignatureAlgoMapping (read the
@see notes in the comments of these properties for more information).
This lib currently supports the following canonicalization methods:
- Canonical XML (
- Canonical XML with comments (
- Exclusive canonical XML (
- Exclusive canonical XML with comments (
These can be extended by adding the necessary class constants. If you do add a new C14N method, remember to add its specific options to the
In order to specify a different C14N method, call the
XmlDsig\XmlDigitalSignature.setCanonicalMethod(c14n) method with the appropriate
Default: Canonical XML.
To force the resulting XML to contain the standalone pseudo-attribute set to
yes simply call the
Node namespace prefixes
To specify a different ns prefix (or you don't want to use one at all), simply pass the appropriate value to the
Public/private key generation
Skip this section and go to usage if your key pairs are already generated.
There are many ways to generate a key pair, however below are examples of RSA key generation using OpenSSL (unix terminal).
Private RSA key
openssl genrsa -aes256 -out private.pem 2048
The above command will generate a private AES256 RSA key with a 2048 modulus. Setting a passphrase is highly recommended.
Public key (PEM format)
openssl rsa -in private.pem -pubout -out public.pem
The above command generates a public certificate in PEM format, based on the previously generated (or already existing) private key.
Public key (X.509 format)
openssl req -x509 -new -key private.pem -days 3650 -out public.crt
The above command generates a public X.509 certificate valid for 3650 days. You will also be prompted for some trivial information needed to generate this certificate (CSR). The resulting key is also known as a self signed certificate.
Public key (XML format)
If you need the public key to be attached to the signed XML document in XML format, you will first have to generate a public certificate (either in PEM or X.509 format). Once you have done this, you can convert your key to an XML format.
Public RSA X.509 certificates can be converted to XML format using http://tools.ailon.org/tools/XmlKey.
Public RSA PEM certificates, on the other hand, can be converted to XML format using https://superdry.apphb.com/tools/online-rsa-key-converter.
Once you have generated your keys and configured the environment then you are ready to start loading keys and adding objects. The methods are explained below.
Loading the generated keys
Once you have generated the appropriate private, public and XML keys (if necessary), you can load them using the
XmlDsig\XmlDigitalSignature.loadPublicXmlKey() methods, respectively.
Object data (strings or DOMNodes) can be added to the XML document using the
XmlDsig\XmlDigitalSignature.addObject() method. If the value of the object needs to be hashed, be sure to pass
true as the third paramater of the aforementioned method.
The resulting data will be placed inside of an
<Object/> node, and an appropriate
<Reference/> element set will be generated, containing the digest of the object.
Signing the document
What may seem trivial by now, you sign the generated XML document using the
XmlDsig\XmlDigitalSignature.sign() method. Of course, be sure to watch out for the return values of the method and any exceptions it might throw.
Verifying the signatures
In turn, signatures may be verified using the
Additionally you can use the Aleksey validator to check dsigs. However, be aware that this validator is faulty. Namely:
- The public key must be embedded into the XML markup.
- Valid documents that are "pretty-printed" fail validation, but pass once the extra tabs/newlines are removed.
- It only works with RSA encryption.
Returning the document
XmlDsig\XmlDigitalSignature.getSignedDocument() returns the canonicalized XML markup as a string.