README

Features

• Sign XML Documents with Digital Signatures (XMLDSIG)
• Verify the Digital Signatures of XML Documents
• ECDSA (SHA256) signature

Requirements

• PHP 8.1 - 8.5
• The openssl extension
• A X.509 digital certificate

Installation

composer require selective/xmldsig

Usage

Signing an XML Document with a digital signature

Input file: example.xml

<?xml version="1.0"?>
<root>
    <creditcard>
        <number>19834209</number>
        <expiry>02/02/2025</expiry>
    </creditcard>
</root>

Load and add the private key to the PrivateKeyStore:

use Selective\XmlDSig\PrivateKeyStore;
// ...

$privateKeyStore = new PrivateKeyStore();

// load a private key from a string
$privateKeyStore->loadFromPem('private key content', 'password');

// or load a private key from a PEM file
$privateKeyStore->loadFromPem(file_get_contents('filename.pem'), 'password');

// load pfx PKCS#12 certificate from a string
$privateKeyStore->loadFromPkcs12('pfx content', 'password');

// or load PKCS#12 certificate from a file
$privateKeyStore->loadFromPkcs12(file_get_contents('filename.p12'), 'password');

Define the digest method: sha1, sha224, sha256, sha384, sha512

use Selective\XmlDSig\Algorithm;

$algorithm = new Algorithm(Algorithm::METHOD_SHA1);

Create a CryptoSigner instance:

use Selective\XmlDSig\CryptoSigner;

$cryptoSigner = new CryptoSigner($privateKeyStore, $algorithm);

Signing:

use Selective\XmlDSig\XmlSigner;

// Create a XmlSigner and pass the crypto signer
$xmlSigner = new XmlSigner($cryptoSigner);

// Optional: Set reference URI
$xmlSigner->setReferenceUri('');

// Create a signed XML string
$signedXml = $xmlSigner->signXml('<?xml ...');

// or sign an XML file
$signedXml = $xmlSigner->signXml(file_get_contents($filename));

// or sign an DOMDocument
$xml = new DOMDocument();
$xml->preserveWhiteSpace = true;
$xml->formatOutput = false;
$xml->loadXML($data);

$signedXml = $xmlSigner->signDocument($xml);

Output:

<?xml version="1.0"?>
<root>
    <creditcard>
        <number>19834209</number>
        <expiry>02/02/2025</expiry>
    </creditcard>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
            <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512"/>
                <DigestValue>Base64EncodedValue==</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>AnotherBase64EncodedValue===</SignatureValue>
    </Signature>
</root>

Signing only specific part of an XML document

Example:

use Selective\XmlDSig\Algorithm;
use Selective\XmlDSig\CryptoSigner;
use Selective\XmlDSig\PrivateKeyStore;
use Selective\XmlDSig\XmlSigner;
use DOMDocument;
use DOMXPath;
// ...

// Load the XML content you want to sign
$xml = new DOMDocument();
$xml->preserveWhiteSpace = true;
$xml->formatOutput = false;
$xml->loadXML($data);

// Create a XPATH query to select the element you want to sign 
$xpath = new DOMXPath($xml);

// Change this query according to your requirements
$referenceUri = '#1';
$elementToSign = $xpath->query( '//*[@Id="'. $referenceUri .'"]' )->item(0);

// Add private key
$privateKeyStore = new PrivateKeyStore();
$privateKeyStore->loadPrivateKey('private key content', 'password');

$cryptoSigner = new CryptoSigner($privateKeyStore, new Algorithm(Algorithm::METHOD_SHA1));

// Sign the element
$xmlSigner = new XmlSigner($cryptoSigner);
$signedXml = $xmlSigner->signDocument($xml, $elementToSign);

Signing an XML Document with ECDSA SHA256

The Elliptic Curve Digital Signature Algorithm (ECDSA) is the elliptic curve analogue of the Digital Signature Algorithm (DSA).

It is compatible with OpenSSL and uses elegant math such as Jacobian Coordinates to speed up the ECDSA on pure PHP.

Requirements

• The GMP extension must be installed and enabled.

To install the package with Composer, run:

composer require starkbank/ecdsa

Example

Note, you can sign an XML signature using ECDSA. It's not supported to use ECDSA for the digest.

You can find a fully working example in the XmlEcdsaTest test class.

Verify the Digital Signatures of XML Documents

Load the public key(s):

use Selective\XmlDSig\PublicKeyStore;
use Selective\XmlDSig\CryptoVerifier;
use Selective\XmlDSig\XmlSignatureVerifier;

$publicKeyStore = new PublicKeyStore();

// load a public key from a string
$publicKeyStore->loadFromPem('public key content');

// or load a public key file
$publicKeyStore->loadFromPem(file_get_contents('cacert.pem'));

// or load a public key from a PKCS#12 certificate string
$publicKeyStore->loadFromPkcs12('public key content', 'password');

// or load a public key from a PKCS#12 certificate file
$publicKeyStore->loadFromPkcs12(file_get_contents('filename.pfx'), 'password');

// Load public keys from DOMDocument X509Certificate nodes
$publicKeyStore->loadFromDocument($xml);

// Load public key from existing OpenSSLCertificate resource
$publicKeyStore->loadFromCertificate($certificate);

Create a CryptoVerifier instance:

use Selective\XmlDSig\CryptoVerifier;

$cryptoVerifier = new CryptoVerifier($publicKeyStore);

Verifying:

use Selective\XmlDSig\XmlSignatureVerifier;

// Create a verifier instance and pass the crypto decoder
$xmlSignatureVerifier = new XmlSignatureVerifier($cryptoVerifier);

// Verify XML from a string
$isValid = $xmlSignatureVerifier->verifyXml($signedXml);

// or verify a XML file
$isValid = $xmlSignatureVerifier->verifyXml(file_get_contents('signed.xml'));

// or verifying an DOMDocument instance
$xml = new DOMDocument();
$xml->preserveWhiteSpace = true;
$xml->formatOutput = false;
$xml->loadXML($data);

$isValid = $xmlSignatureVerifier->verifyDocument($xml);

if ($isValid === true) {
    echo 'The XML signature is valid.';
} else {
    echo 'The XML signature is not valid.';
}

Online XML Digital Signature Verifier

Try these excellent online tools to verify XML signatures:

• https://www.aleksey.com/xmlsec/xmldsig-verifier.html
• https://tools.chilkat.io/xmlDsigVerify.cshtml

Similar libraries

• https://github.com/robrichards/xmlseclibs

License

The MIT License (MIT). Please see License File for more information.