XMLSecLibs

https://github.com/robrichards/xmlseclibs
Admin
XMLSecLibs is a PHP library for working with XML Encryption and Signatures, providing robust...
Tokens:19,955
Snippets:239
Trust Score:7.7
License:BSD-3-Clause
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install xmlseclibs via Composer

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Use this command to add the library to your project dependencies.

```sh
php composer.phar require "robrichards/xmlseclibs"
```

--------------------------------

### Complete Decryption Workflow

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

This example demonstrates the full process of locating encrypted data, resolving the session key using a private key, and decrypting the node.

```php
use RobRichards\XMLSecLibs\XMLSecEnc;
use RobRichards\XMLSecLibs\XMLSecurityKey;

$doc = new DOMDocument();
$doc->load('encrypted.xml');

$objenc = new XMLSecEnc();

// Optional: Enforce algorithm policies
$objenc->allowedDataAlgorithms = XMLSecEnc::DEFAULT_DATA_ALGORITHMS;
$objenc->allowedKeyAlgorithms = XMLSecEnc::DEFAULT_KEY_ALGORITHMS;

// Locate encrypted data
$encData = $objenc->locateEncryptedData($doc);
if (!$encData) {
    throw new Exception('Cannot locate EncryptedData');
}

$objenc->setNode($encData);
$objenc->type = $encData->getAttribute('Type');

// Determine data-encryption algorithm
$dataKey = $objenc->locateKey();
if (!$dataKey) {
    throw new Exception('Unknown data encryption algorithm');
}

// Resolve the session key
if ($keyInfo = $objenc->locateKeyInfo($dataKey)) {
    if ($keyInfo->isEncrypted) {
        // Load trusted private key to unwrap the session key
        $privKey = new XMLSecurityKey(XMLSecurityKey::RSA_OAEP, ['type' => 'private']);
        $privKey->loadKey('/path/to/your-private-key.pem', true);
        
        $sessionKey = $keyInfo->encryptedCtx->decryptKey($keyInfo);
        $dataKey->loadKey($sessionKey);
    }
}

// Decrypt
$decrypted = $objenc->decryptNode($dataKey, true);
$doc->save('decrypted.xml');
```

--------------------------------

### Install phpseclib dependency

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Use Composer to install the required phpseclib version for cryptographic operations.

```bash
composer require phpseclib/phpseclib:~3.0
```

--------------------------------

### Generate a GUID for XML IDs

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Creates a unique identifier string with a specified prefix.

```php
$guid = XMLSecurityDSig::generateGUID('sig'); // "sig12345678-abcd-ef01-..."
```

--------------------------------

### XPath Filtering Transform Configuration

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/types.md

Structure for XPath Filtering Transform configuration and example usage for addReference().

```php
array{
    query: string,                 // The XPath expression wrapped in filter predicate
    namespaces: array<string, string>,  // Namespace prefix => URI mappings in scope
}
```

```php
$arTransforms = [
    [
        'http://www.w3.org/TR/1999/REC-xpath-19991116' => [
            'query' => 'ancestor::item',
            'namespaces' => ['soap' => 'http://schemas.xmlsoap.org/soap/envelope/'],
        ]
    ]
];
```

--------------------------------

### Get Symmetric Key Size

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Retrieves the required key size in bytes for the configured symmetric algorithm.

```php
$key = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$size = $key->getSymmetricKeySize(); // Returns 32
```

--------------------------------

### Initialize XMLSecurityKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Demonstrates creating instances for RSA signing, AES encryption, and HMAC operations.

```php
use RobRichards\XMLSecLibs\XMLSecurityKey;

// RSA key for signing (requires type parameter)
$signKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);

// AES encryption key (symmetric)
$encKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);

// HMAC key (symmetric)
$hmacKey = new XMLSecurityKey(XMLSecurityKey::HMAC_SHA1);
```

--------------------------------

### Initialize XMLSecEnc

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Demonstrates creating an instance of XMLSecEnc with default settings or with whitespace stripping enabled.

```php
use RobRichards\XMLSecLibs\XMLSecEnc;

// Standard template with whitespace
$objenc = new XMLSecEnc();

// Compact template (no whitespace)
$objenc = new XMLSecEnc(['stripWhitespace' => true]);
```

--------------------------------

### Initialize XMLSecurityDSig Object

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Demonstrates instantiation of the XMLSecurityDSig class with default, custom, and compact configuration options.

```php
use RobRichards\XMLSecLibs\XMLSecurityDSig;

// Standard namespace prefix 'ds'
$objDSig = new XMLSecurityDSig();

// Custom prefix
$objDSig = new XMLSecurityDSig('sig');

// Compact template (no whitespace)
$objDSig = new XMLSecurityDSig('ds', ['stripWhitespace' => true]);
```

--------------------------------

### Sign an XML Document

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Demonstrates the process of setting up a signature, loading a private key, and appending the signature to a DOM document.

```php
$doc = new DOMDocument();
$doc->load('document.xml');

$objDSig = new XMLSecurityDSig();
$objDSig->setCanonicalMethod(XMLSecurityDSig::EXC_C14N);
$objDSig->addReference($doc, XMLSecurityDSig::SHA256, [XMLSecurityDSig::ENVELOPED]);

$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);
$objKey->loadKey('/path/to/key.pem', true);
$objKey->passphrase = 'password'; // if encrypted

$objDSig->sign($objKey);
$objDSig->appendSignature($doc->documentElement);
$doc->save('signed.xml');
```

--------------------------------

### Load Key Material

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Demonstrates loading keys from files, certificates, or strings, including handling encrypted private keys with passphrases.

```php
// Load private key from file
$key = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);
$key->loadKey('/path/to/privatekey.pem', true);

// Load certificate for public key extraction
$pubKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$pubKey->loadKey('/path/to/cert.pem', true, true);

// Load symmetric key from PEM string
$symKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$symKey->loadKey($keyData, false);

// With passphrase for encrypted private key
$key->passphrase = 'my-passphrase';
$key->loadKey($encryptedKeyPEM, false);
```

--------------------------------

### Initialize XMLSecurityDSig

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Configure signature elements with custom namespace prefixes or compact templates.

```php
public function __construct(string $prefix = 'ds', ?array $options = null)
```

```php
// Standard 'ds' prefix
$sig = new XMLSecurityDSig();

// Custom prefix 'sig'
$sig = new XMLSecurityDSig('sig');

// No prefix
$sig = new XMLSecurityDSig('');

// Compact template
$sig = new XMLSecurityDSig('ds', ['stripWhitespace' => true]);
```

--------------------------------

### Initialize XMLSecEnc

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Configure encryption instances with optional whitespace stripping.

```php
public function __construct(?array $options = null)
```

```php
// Standard template with whitespace
$enc = new XMLSecEnc();

// Compact template
$enc = new XMLSecEnc(['stripWhitespace' => true]);
```

--------------------------------

### Sign an XML document with SHA-256

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Demonstrates loading an XML file, signing it with an RSA private key, and appending the signature. Ensure the private key and certificate paths are correctly configured.

```php
use RobRichards\XMLSecLibs\XMLSecurityDSig;
use RobRichards\XMLSecLibs\XMLSecurityKey;

// Load the XML to be signed
$doc = new DOMDocument();
$doc->load('./path/to/file/tobesigned.xml');

// Create a new Security object 
$objDSig = new XMLSecurityDSig();
// Use the c14n exclusive canonicalization
$objDSig->setCanonicalMethod(XMLSecurityDSig::EXC_C14N);
// Sign using SHA-256
$objDSig->addReference(
    $doc, 
    XMLSecurityDSig::SHA256, 
    array('http://www.w3.org/2000/09/xmldsig#enveloped-signature')
);

// Create a new (private) Security key
$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, array('type'=>'private'));
/*
If key has a passphrase, set it using
$objKey->passphrase = '<passphrase>';
*/
// Load the private key
$objKey->loadKey('./path/to/privatekey.pem', TRUE);

// Sign the XML file
$objDSig->sign($objKey);

// Add the associated public key to the signature
$objDSig->add509Cert(file_get_contents('./path/to/file/mycert.pem'));

// Append the signature to the XML
$objDSig->appendSignature($doc->documentElement);
// Save the signed XML
$doc->save('./path/to/signed.xml');
```

--------------------------------

### Enable Legacy Interoperability Mode

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Restore legacy settings in one place for interoperability with older peers, though migration is preferred.

```php
$objDSig->enableLegacyMode();
$objenc->enableLegacyMode();
```

--------------------------------

### Enable Legacy Mode

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Use this method to restore pre-4.0 interoperability defaults by setting allowRSA15KeyTransport to true.

```php
$objenc = new XMLSecEnc();
$objenc->enableLegacyMode(); // For backward compatibility with old peers
```

--------------------------------

### Enable RSA-1.5 Key Transport

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Opt-in to RSA-1.5 key transport for legacy interop, noting that it is denied by default due to Bleichenbacher risks.

```php
$objenc->allowRSA15KeyTransport = true;
```

--------------------------------

### Configure XMLSecurityKey runtime properties

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Set the passphrase and key name before loading an encrypted private key.

```php
$privKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);
$privKey->passphrase = 'my-secret-passphrase';
$privKey->loadKey('/path/to/encrypted-key.pem', true);
$privKey->name = 'MySigningKey';
```

--------------------------------

### Define Default Key Algorithms

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/types.md

Recommended key-transport algorithms, excluding RSA-1.5 by default.

```php
array(
    XMLSecurityKey::RSA_OAEP,
    XMLSecurityKey::RSA_OAEP_MGF1P,
)
```

--------------------------------

### Configure XMLSecEnc algorithm policies

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Apply secure defaults, enable legacy modes, or define custom algorithm allowlists for key transport and data encryption.

```php
$enc = new XMLSecEnc();

// Strict secure defaults (recommended)
$enc->allowedKeyAlgorithms = XMLSecEnc::DEFAULT_KEY_ALGORITHMS;
$enc->allowedDataAlgorithms = XMLSecEnc::DEFAULT_DATA_ALGORITHMS;

// Legacy mode for backward compatibility
$enc->enableLegacyMode(); // Equivalent to: $enc->allowRSA15KeyTransport = true;

// Custom policy (RSA-OAEP only, AES-GCM only)
$enc->allowedKeyAlgorithms = [XMLSecurityKey::RSA_OAEP];
$enc->allowedDataAlgorithms = [
    XMLSecurityKey::AES128_GCM,
    XMLSecurityKey::AES256_GCM,
];
```

--------------------------------

### Allow File Scheme in Certificate Fetching

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Pass the allow_file_scheme option to enable file:// URI support when fetching certificates.

```php
array('allow_file_scheme' => true)
```

--------------------------------

### Define Namespace and Imports

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/README.md

Standard namespace declaration and class imports for using XMLSecLibs components.

```php
namespace RobRichards\XMLSecLibs;
```

```php
use RobRichards\XMLSecLibs\XMLSecurityKey;
use RobRichards\XMLSecLibs\XMLSecurityDSig;
use RobRichards\XMLSecLibs\XMLSecEnc;
```

--------------------------------

### Configure Signature Algorithm Allowlist

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Explicitly widen the allowed signature algorithms for legacy interoperability.

```php
$objDSig->allowedSignatureAlgorithms[] = XMLSecurityKey::RSA_SHA1;
```

--------------------------------

### XMLSecurityDSig::__construct

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Initializes a new XMLSecurityDSig object with an optional namespace prefix and configuration options.

```APIDOC
## __construct(string $prefix = 'ds', ?array $options = null)

### Description
Initializes a new signature object with an optional namespace prefix and configuration options.

### Parameters
- **$prefix** (string) - Optional - XML namespace prefix for signature elements (default: 'ds').
- **$options** (array|null) - Optional - Configuration flags, such as ['stripWhitespace' => true] for compact templates.

### Return Type
void
```

--------------------------------

### Locate an encryption key with PHP

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Instantiates a key object based on the EncryptionMethod found in the document.

```php
$objenc = new XMLSecEnc();
$encData = $objenc->locateEncryptedData($doc);
$objenc->setNode($encData);

$key = $objenc->locateKey();
if (!$key) {
    throw new Exception('Unknown encryption algorithm');
}
```

--------------------------------

### XMLSecEnc::__construct

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Initializes a new XML encryption context with optional configuration flags.

```APIDOC
## __construct

### Description
Initializes a new XML encryption context.

### Signature
`public function __construct(?array $options = null)`

### Parameters
- **$options** (array|null) - Optional - Optional flags: ['stripWhitespace' => true] for compact template.

### Example
```php
use RobRichards\XMLSecLibs\XMLSecEnc;

// Standard template with whitespace
$objenc = new XMLSecEnc();

// Compact template (no whitespace)
$objenc = new XMLSecEnc(['stripWhitespace' => true]);
```
```

--------------------------------

### Enable Legacy Interoperability

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Use legacy mode to support older documents by relaxing security constraints like Doctype and RSA-1.5 transport.

```php
$sig = new XMLSecurityDSig();
$sig->enableLegacyMode();
// Sets: forbidDoctype = false, allowXPathTransforms = true, uncapped limits

$enc = new XMLSecEnc();
$enc->enableLegacyMode();
// Sets: allowRSA15KeyTransport = true

// Now accept pre-4.0 documents/messages
```

--------------------------------

### Locate Key Info Statically

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Provides a static method for locating key information with built-in DoS protection against deep EncryptedKey chains.

```php
public static function staticLocateKeyInfo(
    ?XMLSecurityKey $objBaseKey = null,
    ?DOMNode $node = null,
    int $depth = 0,
    bool $allowRSA15 = false
): ?XMLSecurityKey
```

```php
$key = XMLSecEnc::staticLocateKeyInfo(null, $encKeyElement, 0, false);
```

--------------------------------

### Retrieve the algorithm URI

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Returns the full algorithm URI associated with the key instance.

```php
$key = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
echo $key->getAlgorithm(); // "http://www.w3.org/2009/xmlenc11#aes256-gcm"
```

--------------------------------

### loadKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Loads key material from a string or file path into the XMLSecurityKey instance.

```APIDOC
## loadKey

### Description
Loads key material from a string or file path. This method supports loading PEM strings, file paths, and extracting public keys from X.509 certificates.

### Signature
`public function loadKey(string $key, bool $isFile = false, bool $isCert = false): void`

### Parameters
- **$key** (string) - Required - Key data (PEM string) or file path
- **$isFile** (bool) - Optional - If true, $key is treated as a file path
- **$isCert** (bool) - Optional - If true, $key is an X.509 certificate (extracts public key)

### Throws
- `Exception` when the file cannot be read, certificate parsing fails, key size is insufficient, or HMAC keys are loaded from asymmetric material.
```

--------------------------------

### Enable Legacy Compatibility Mode

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/README.md

Restores support for older features like DOCTYPE, XPath Filtering, and RSA-1.5 key transport. Use only for backward compatibility with pre-4.0 documents.

```php
$sig = new XMLSecurityDSig();
$sig->enableLegacyMode(); // Accepts DOCTYPE, XPath, uncapped XPath limits

$enc = new XMLSecEnc();
$enc->enableLegacyMode(); // Accepts RSA-1.5 key transport
```

--------------------------------

### Verify an XML Document

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Recommended entry point for signature verification using a trusted public key. Always operate on the returned validated nodes.

```php
$doc = new DOMDocument();
$doc->load('signed.xml');

$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$objKey->loadKey('/path/to/trusted-cert.pem', true, true);

$objDSig = new XMLSecurityDSig();

// Optional: declare custom ID attributes (e.g., for SAML wsu:Id)
// $objDSig->idKeys = ['wsu:Id'];
// $objDSig->idNS = ['wsu' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'];

try {
    $validatedNodes = $objDSig->verifyDocument($objKey, $doc);
    // Operate ONLY on $validatedNodes from here on
    foreach ($validatedNodes as $id => $node) {
        echo "Validated node: $id\n";
    }
} catch (Exception $e) {
    echo "Verification failed: " . $e->getMessage();
}
```

--------------------------------

### getAlgorithm

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Retrieves the full algorithm URI associated with the key.

```APIDOC
## getAlgorithm()

### Description
Returns the full algorithm URI for this key.

### Returns
- **string** - Algorithm URI (e.g., "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256")
```

--------------------------------

### XMLSecurityKey::__construct

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Initializes a new instance of the XMLSecurityKey class with a specified algorithm type and optional parameters.

```APIDOC
## __construct(string $type, ?array $params = null)

### Description
Initializes a cryptographic key with a specified algorithm type.

### Parameters
- **$type** (string) - Required - Algorithm type constant (e.g., XMLSecurityKey::RSA_SHA256, XMLSecurityKey::AES256_CBC)
- **$params** (array|null) - Optional - Additional parameters; for asymmetric algorithms, must include ['type' => 'public'|'private']

### Returns
- **void**

### Throws
- **Exception** - Thrown when an invalid key type is provided or required parameters are missing.
```

--------------------------------

### Enable Legacy Compatibility Mode

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Configures the signature object to support older document formats and XPath transforms.

```php
$objDSig = new XMLSecurityDSig();
$objDSig->enableLegacyMode(); // Accept old document formats
$objDSig->verifyDocument($key, $doc);
```

--------------------------------

### Retrieve the X.509 certificate

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Returns the certificate in PEM format if the key was loaded from a certificate, otherwise returns null.

```php
$key = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$key->loadKey('/path/to/cert.pem', true, true);

$cert = $key->getX509Certificate();
```

--------------------------------

### Verify a signature with XMLSecurityKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Use strict comparison (=== 1) when checking the result, as -1 is truthy in PHP.

```php
$key = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$key->loadKey($certPem, false, true);

$result = $key->verifySignature($data, $signature);
if ($result === 1) {
    echo "Signature is valid";
} elseif ($result === 0) {
    echo "Signature is invalid";
} else {
    echo "Verification error";
}
```

--------------------------------

### Define XMLSecurityDSig::DEFAULT_SIGNATURE_ALGORITHMS

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Lists the recommended SignatureMethod URIs used by verifyDocument when allowedSignatureAlgorithms is null.

```php
array(
    XMLSecurityKey::RSA_SHA256,
    XMLSecurityKey::RSA_SHA384,
    XMLSecurityKey::RSA_SHA512,
    XMLSecurityKey::RSA_SHA256_MGF1,
)
```

--------------------------------

### verifyDocument(XMLSecurityKey $objKey, DOMDocument|DOMNode $objDoc, int $pos = 0): array

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Recommended entry point for signature verification. Safe by default: requires a caller-supplied pinned key, enforces strong algorithm allowlists, and validates all references.

```APIDOC
## verifyDocument(XMLSecurityKey $objKey, DOMDocument|DOMNode $objDoc, int $pos = 0): array

### Description
Recommended entry point for signature verification. Safe by default: requires a caller-supplied pinned key, enforces strong algorithm allowlists, and validates all references.

### Parameters
- **$objKey** (XMLSecurityKey) - Required - Trusted/pinned verification key (NOT read from document)
- **$objDoc** (DOMDocument|DOMNode) - Required - Document to verify
- **$pos** (int) - Optional - Which Signature to verify (if multiple exist)

### Return Type
- array: Associative array of validated node IDs and nodes (e.g., ['id' => DOMNode, ...]). Never empty on success.

### Throws
- Exception: On any verification failure (no signature found, algorithm not allowed, reference validation failed, signature invalid, etc.).
```

--------------------------------

### Convert RSA Components to PEM

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Converts raw RSA modulus and exponent into PEM format. Throws an Exception on failure.

```php
public static function convertRSA(string $modulus, string $exponent): string
```

--------------------------------

### Enable XPath Transforms

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Enable XPath transforms only when verifying signatures from trusted sources, as they pose a pre-authentication CPU denial-of-service risk.

```php
$objDSig->allowXPathTransforms = true
```

--------------------------------

### Register nodes for encryption with PHP

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Adds DOM nodes to the reference list for subsequent bulk encryption.

```php
$objenc = new XMLSecEnc();
$objenc->addReference('item1', $elem1, XMLSecEnc::Element);
$objenc->addReference('item2', $elem2, XMLSecEnc::Element);

$sessionKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$sessionKey->generateSessionKey();

$objenc->encryptReferences($sessionKey);
```

--------------------------------

### enableLegacyMode

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Restores pre-4.0 interoperability defaults.

```APIDOC
## enableLegacyMode

### Description
Restores pre-4.0 interoperability defaults. Sets forbidDoctype = false, allowXPathTransforms = true, and lifts XPath transform count limits.

### Return Type
XMLSecurityDSig (self) — For method chaining.
```

--------------------------------

### Verify an XML signature with a pinned key

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Use this pattern to securely verify XML signatures by pinning a trusted key or certificate instead of relying on document-provided keys.

```php
use RobRichards\XMLSecLibs\XMLSecurityDSig;
use RobRichards\XMLSecLibs\XMLSecurityKey;

$doc = new DOMDocument();
$doc->load('./path/to/signed.xml');

// Pin the key/certificate you trust (do NOT read it from the document).
$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, array('type' => 'public'));
$objKey->loadKey('./path/to/trusted-cert.pem', true, true);

$objDSig = new XMLSecurityDSig();
// If assertions use custom Id attributes (e.g. WS-Security), declare them first:
// $objDSig->idKeys = array('wsu:Id');
// $objDSig->idNS   = array('wsu' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd');

try {
    // Throws on any failure; returns the validated nodes on success.
    $validatedNodes = $objDSig->verifyDocument($objKey, $doc);
    // Operate ONLY on $validatedNodes from here on.
} catch (Exception $e) {
    // Verification failed - reject the message.
}
```

--------------------------------

### Configure PSR-4 Autoloading

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Add the namespace mapping to your composer.json file to enable PSR-4 autoloading for the library.

```json
{
  "autoload": {
    "psr-4": {
      "RobRichards\\XMLSecLibs\\": "src"
    }
  }
}
```

--------------------------------

### staticLocateKeyInfo

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

A static method to locate key information, providing DoS protection against deep EncryptedKey chains.

```APIDOC
## staticLocateKeyInfo

### Description
Static version of `locateKeyInfo()` for use outside instance context. Includes DoS protection against deep EncryptedKey chains.

### Signature
`public static function staticLocateKeyInfo(?XMLSecurityKey $objBaseKey = null, ?DOMNode $node = null, int $depth = 0, bool $allowRSA15 = false): ?XMLSecurityKey`

### Parameters
- **$objBaseKey** (XMLSecurityKey|null) - Optional (Default: null) - Base key to populate
- **$node** (DOMNode|null) - Optional (Default: null) - Node containing KeyInfo
- **$depth** (int) - Optional (Default: 0) - Current recursion depth
- **$allowRSA15** (bool) - Optional (Default: false) - Whether to permit RSA-1.5 key transport

### Returns
- **XMLSecurityKey|null**

### Throws
- `Exception` when recursion depth exceeds `MAX_KEYINFO_DEPTH` (10).

### Example
```php
$key = XMLSecEnc::staticLocateKeyInfo(null, $encKeyElement, 0, false);
```
```

--------------------------------

### XMLSecurityKey Constructor Signature

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

The constructor signature for initializing a new cryptographic key instance.

```php
public function __construct(string $type, ?array $params = null)
```

--------------------------------

### Define XMLSecurityDSig::DEFAULT_DIGEST_ALGORITHMS

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Lists the recommended DigestMethod URIs used by verifyDocument when allowedDigestAlgorithms is null.

```php
array(
    XMLSecurityDSig::SHA256,
    XMLSecurityDSig::SHA384,
    XMLSecurityDSig::SHA512,
)
```

--------------------------------

### Implement Secure Signature Verification

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Configure signature and digest algorithms and verify a document using a trusted public key.

```php
$sig = new XMLSecurityDSig();
$sig->allowedSignatureAlgorithms = XMLSecurityDSig::DEFAULT_SIGNATURE_ALGORITHMS;
$sig->allowedDigestAlgorithms = XMLSecurityDSig::DEFAULT_DIGEST_ALGORITHMS;
// forbidDoctype already true (default)
// allowXPathTransforms already false (default)

$trustedKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$trustedKey->loadKey('/path/to/trusted-cert.pem', true, true);

$validatedNodes = $sig->verifyDocument($trustedKey, $doc);
```

--------------------------------

### Add X.509 Certificate to Signature

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Demonstrates adding certificates via PEM strings, URLs, or with specific issuer/subject options.

```php
$objDSig = new XMLSecurityDSig();
// ... sign operations ...

// Add certificate directly
$certPem = file_get_contents('/path/to/cert.pem');
$objDSig->add509Cert($certPem);

// Add certificate from HTTPS URL
$objDSig->add509Cert('https://example.com/cert.pem', true, true);

// Add issuer and subject information
$objDSig->add509Cert($certPem, true, false, ['issuerSerial' => true, 'subjectName' => true]);
```

--------------------------------

### sign(XMLSecurityKey $objKey, ?DOMNode $appendToNode = null): void

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Generates the signature and inserts the SignatureValue into the Signature element.

```APIDOC
## sign(XMLSecurityKey $objKey, ?DOMNode $appendToNode = null): void

### Description
Generates the signature and inserts SignatureValue into the Signature element.

### Parameters
- **$objKey** (XMLSecurityKey) - Required - Private key for signing
- **$appendToNode** (DOMNode|null) - Optional - If provided, appends the signature to this node first

### Throws
- Exception: When canonicalization method is not set or signature context is invalid.
```

--------------------------------

### encryptKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Wraps (encrypts) a session key with a key-transport algorithm, creating an EncryptedKey element.

```APIDOC
## encryptKey(XMLSecurityKey $srcKey, XMLSecurityKey $rawKey, bool $append = true)

### Description
Wraps (encrypts) a session key with a key-transport algorithm, creating an EncryptedKey element.

### Parameters
- **$srcKey** (XMLSecurityKey) - Required - Key-transport key (public key for RSA-OAEP)
- **$rawKey** (XMLSecurityKey) - Required - Session key to wrap (AES, 3DES, etc.)
- **$append** (bool) - Optional (Default: true) - Append EncryptedKey to KeyInfo in the template; false leaves in $this->encKey

### Returns
- **void**

### Throws
- **Exception** on encryption or element creation failure.
```

--------------------------------

### Encrypt a session key with PHP

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Wraps a symmetric session key using a public key-transport key.

```php
$objenc = new XMLSecEnc();

// Session key (symmetric)
$sessionKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$sessionKey->generateSessionKey();

// Key-transport key (public key)
$kekKey = new XMLSecurityKey(XMLSecurityKey::RSA_OAEP, ['type' => 'public']);
$kekKey->loadKey('/path/to/publickey.pem', false, true);

// Wrap the session key
$objenc->encryptKey($kekKey, $sessionKey, true);
```

--------------------------------

### Add X.509 Certificate Statically

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Adds an X.509 certificate to a signature node without requiring an instance of the class.

```php
$xpath = new DOMXPath($doc);
XMLSecurityDSig::staticAdd509Cert($sigNode, $certPem, true, false, $xpath);
```

--------------------------------

### Define Default Data Algorithms

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/types.md

Recommended data-encryption algorithms, restricted to authenticated GCM modes.

```php
array(
    XMLSecurityKey::AES128_GCM,
    XMLSecurityKey::AES192_GCM,
    XMLSecurityKey::AES256_GCM,
)
```

--------------------------------

### add509Cert

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Adds an X.509 certificate to the signature's KeyInfo.

```APIDOC
## add509Cert

### Description
Adds an X.509 certificate to the signature's KeyInfo.

### Parameters
- **$cert** (string) - Required - PEM certificate or URL
- **$isPEMFormat** (bool) - Optional (default: true) - true for PEM string, false for DER binary
- **$isURL** (bool) - Optional (default: false) - If true, $cert is a URL to fetch
- **$options** (array|null) - Optional (default: null) - Options: ['issuerSerial' => true, 'subjectName' => true, 'allow_file_scheme' => true]

### Return Type
void

### Throws
Exception on fetch failure, invalid certificate, or URL issues.
```

--------------------------------

### locateKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Locates and instantiates a key object based on the EncryptionMethod in the document.

```APIDOC
## locateKey(?DOMNode $node = null)

### Description
Locates and instantiates a key object based on the EncryptionMethod in the document.

### Parameters
- **$node** (DOMNode|null) - Optional (Default: null) - Node to search; uses $this->rawNode if null

### Returns
- **XMLSecurityKey|null** - Key object with algorithm set, or null if algorithm is unknown.

### Throws
- **Exception** when algorithm policy is violated.
```

--------------------------------

### Encrypt References

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Encrypts all nodes previously registered via addReference using the provided XMLSecurityKey.

```php
public function encryptReferences(XMLSecurityKey $objKey): void
```

--------------------------------

### verify(XMLSecurityKey $objKey): int

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Low-level primitive for verifying a signature. Always check the return value strictly (=== 1).

```APIDOC
## verify(XMLSecurityKey $objKey): int

### Description
Low-level primitive for verifying a signature. Always check the return value strictly (=== 1).

### Parameters
- **$objKey** (XMLSecurityKey) - Required - Public key for verification

### Return Type
- int: 1 (Signature is valid), 0 (Signature is invalid), -1 (An error occurred)

### Throws
- Exception: When SignatureMethod does not match the key type or is not in the allowlist.
```

--------------------------------

### Append Signature to DOM

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Shows how to attach a generated signature to a DOMDocument node.

```php
$doc = new DOMDocument();
$doc->load('document.xml');

$objDSig = new XMLSecurityDSig();
// ... build signature ...
$objDSig->sign($objKey);
$objDSig->appendSignature($doc->documentElement);
$doc->save('signed.xml');
```

--------------------------------

### Verify Signature with Strict Comparison

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Use strict comparison when using low-level primitives to avoid boolean context errors.

```php
$objDSig->verify($key) === 1
```

--------------------------------

### Implement Secure Encryption

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Set allowed algorithms and enforce policy during decryption to prevent insecure key transport.

```php
$enc = new XMLSecEnc();
$enc->allowedKeyAlgorithms = XMLSecEnc::DEFAULT_KEY_ALGORITHMS;
$enc->allowedDataAlgorithms = XMLSecEnc::DEFAULT_DATA_ALGORITHMS;
// allowRSA15KeyTransport already false (default)

// Encryption setup...
$sessionKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$sessionKey->generateSessionKey();

// Decryption with policy enforcement
$objenc->setNode($encData);
$objenc->type = $encData->getAttribute('Type');
$dataKey = $objenc->locateKey();
// Enforce policy: will throw if algorithm not in allowlist
```

--------------------------------

### Sign Data

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Generates a binary signature for the provided data using the loaded private key.

```php
$key = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'private']);
$key->loadKey('/path/to/privatekey.pem', true);

$signature = $key->signData($data);
```

--------------------------------

### Resolve encryption key from KeyInfo with PHP

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Retrieves the encryption key from various KeyInfo elements like EncryptedKey or X509Data.

```php
$objenc = new XMLSecEnc();
$encData = $objenc->locateEncryptedData($doc);
$objenc->setNode($encData);
$objenc->type = $encData->getAttribute('Type');

// Get the data-encryption algorithm
$dataKey = $objenc->locateKey();

// Get the key-encryption key (from EncryptedKey)
if ($keyInfo = $objenc->locateKeyInfo($dataKey)) {
    // keyInfo now has the wrapped session key or key reference
}
```

--------------------------------

### getSymmetricKeySize

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Returns the required key size in bytes for the symmetric algorithm.

```APIDOC
## getSymmetricKeySize

### Description
Returns the required key size in bytes for this symmetric algorithm.

### Signature
`public function getSymmetricKeySize(): ?int`

### Returns
- **int|null** - Byte size (e.g., 32 for AES-256), or null if not a symmetric cipher.
```

--------------------------------

### Decrypt XML with EncryptedKey and EncryptedData

Source: https://github.com/robrichards/xmlseclibs/blob/master/README.md

Use this recipe to decrypt XML documents by unwrapping a session key with a private key. It includes security best practices like pinning algorithm policies.

```php
use RobRichards\XMLSecLibs\XMLSecEnc;
use RobRichards\XMLSecLibs\XMLSecurityKey;

$doc = new DOMDocument();
$doc->load('./path/to/encrypted.xml');

$objenc = new XMLSecEnc();

// Pin the algorithm policy (all optional, but recommended):
//  - RSA-1.5 key transport is already denied by default (Bleichenbacher);
//    only set this if you must interoperate with a legacy peer.
// $objenc->allowRSA15KeyTransport = true;
//  - Restrict data encryption to authenticated AES-GCM (rejects CBC):
$objenc->allowedDataAlgorithms = XMLSecEnc::DEFAULT_DATA_ALGORITHMS;
//  - Restrict key transport to RSA-OAEP:
$objenc->allowedKeyAlgorithms  = XMLSecEnc::DEFAULT_KEY_ALGORITHMS;

$encData = $objenc->locateEncryptedData($doc);
if (! $encData) {
    throw new Exception('Cannot locate EncryptedData');
}
$objenc->setNode($encData);
$objenc->type = $encData->getAttribute('Type');

// Resolve the session key. locateKey() reads the data algorithm from the
// document; locateKeyInfo() finds the EncryptedKey.
$objKey = $objenc->locateKey();
if (! $objKey) {
    throw new Exception('Unknown data encryption algorithm');
}

if ($objKeyInfo = $objenc->locateKeyInfo($objKey)) {
    if ($objKeyInfo->isEncrypted) {
        // Load YOUR trusted private key to unwrap the session key.
        $objKeyInfo->loadKey('./path/to/your-private-key.pem', true);
        $sessionKey = $objKeyInfo->encryptedCtx->decryptKey($objKeyInfo);
        $objKey->loadKey($sessionKey);
    }
}

// If the session key was supplied out-of-band (no EncryptedKey), load it here:
// if (empty($objKey->key)) { $objKey->loadKey($sharedSecretBytes); }

// Decrypted content is returned; a DOCTYPE in the plaintext is rejected.
$decrypted = $objenc->decryptNode($objKey, true);
```

--------------------------------

### locateKeyInfo

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Resolves the encryption key from KeyInfo elements (EncryptedKey, RetrievalMethod, KeyName, X509Data, etc.).

```APIDOC
## locateKeyInfo(?XMLSecurityKey $objBaseKey = null, ?DOMNode $node = null)

### Description
Resolves the encryption key from KeyInfo elements (EncryptedKey, RetrievalMethod, KeyName, X509Data, etc.).

### Parameters
- **$objBaseKey** (XMLSecurityKey|null) - Optional (Default: null) - Existing key object to populate
- **$node** (DOMNode|null) - Optional (Default: null) - Node containing KeyInfo; uses $this->rawNode if null

### Returns
- **XMLSecurityKey|null** - Resolved key or null if not found.

### Throws
- **Exception** on invalid EncryptedKey reference chains (depth exceeded) or key format errors.
```

--------------------------------

### encryptData

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Encrypts data using phpseclib.

```APIDOC
## encryptData

### Description
Encrypts data using phpseclib. Returns ciphertext with IV prepended (and auth tag appended for GCM).

### Signature
`public function encryptData(string $data): ?string`

### Parameters
- **$data** (string) - Required - Plaintext to encrypt

### Throws
- `Exception` on encryption failure or invalid key state.
```

--------------------------------

### Set Canonicalization Method

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityDSig.md

Configures the canonicalization algorithm for the signature using a constant or URI.

```php
$objDSig = new XMLSecurityDSig();
$objDSig->setCanonicalMethod(XMLSecurityDSig::EXC_C14N);
```

--------------------------------

### Retrieve the X.509 thumbprint

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Returns the 40-character SHA-1 thumbprint of the certificate or null if not applicable.

```php
$key = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$key->loadKey('/path/to/cert.pem', true, true);

$thumbprint = $key->getX509Thumbprint(); // e.g., "1a2b3c4d..."
```

--------------------------------

### signData

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Signs data using the key's signature algorithm.

```APIDOC
## signData

### Description
Signs data using the key's signature algorithm.

### Signature
`public function signData(string $data): string`

### Parameters
- **$data** (string) - Required - Data to sign

### Throws
- `Exception` on signing failure.
```

--------------------------------

### Configure Custom ID Attributes

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/README.md

Defines custom ID attributes and namespaces for protocols like SAML or WS-Security that extend beyond standard @Id attributes.

```php
$sig->idKeys = ['wsu:Id', 'AssertionID'];
$sig->idNS = ['wsu' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'];
```

--------------------------------

### Create Key from EncryptedKey Element

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Creates a key object from an XML EncryptedKey element. Throws an Exception if the algorithm is undetermined or the recursion depth is exceeded.

```php
public static function fromEncryptedKeyElement(
    DOMElement $element,
    int $depth = 0,
    bool $allowRSA15 = false
): XMLSecurityKey
```

```php
use RobRichards\XMLSecLibs\XMLSecurityKey;

$doc = new DOMDocument();
$doc->load('encrypted.xml');

$encKeyElements = $doc->getElementsByTagName('EncryptedKey');
if ($encKeyElements->length > 0) {
    $encKeyElement = $encKeyElements->item(0);
    $key = XMLSecurityKey::fromEncryptedKeyElement($encKeyElement);
    // Key is ready to be unwrapped with your private key
}
```

--------------------------------

### Decrypt a session key with PHP

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecEnc.md

Unwraps a session key using a private key.

```php
$privKey = new XMLSecurityKey(XMLSecurityKey::RSA_OAEP, ['type' => 'private']);
$privKey->loadKey('/path/to/privatekey.pem', true);
$privKey->isEncrypted = true;
$privKey->encryptedCtx = $objenc;

$sessionKey = $objenc->decryptKey($privKey);
// Now use sessionKey to decrypt the data
```

--------------------------------

### Configure XMLSecurityDSig security and ID attributes

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/configuration.md

Define custom ID attributes for SAML/WS-Security, enforce strict algorithm policies, and adjust XPath limits for legacy document support.

```php
$sig = new XMLSecurityDSig();

// For SAML assertions with wsu:Id
$sig->idKeys = ['wsu:Id'];
$sig->idNS = ['wsu' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'];

// Strict algorithm policy for high-security context
$sig->allowedSignatureAlgorithms = [XMLSecurityKey::RSA_SHA256];
$sig->allowedDigestAlgorithms = [XMLSecurityDSig::SHA256];

// Relax XPath limits for legacy documents
$sig->maxXPathTransforms = 100;
$sig->maxXPathNamespaces = 200;
```

--------------------------------

### generateSessionKey

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Generates a random session key for symmetric encryption.

```APIDOC
## generateSessionKey

### Description
Generates a random session key for symmetric encryption. The generated key material is returned as a binary string and automatically assigned to the instance.

### Signature
`public function generateSessionKey(): string`

### Throws
- `Exception` when the key type does not support session key generation.
```

--------------------------------

### Encrypt Data

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Encrypts plaintext using the configured algorithm, returning ciphertext with IV and authentication tag.

```php
$key = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$key->generateSessionKey();

$plaintext = "Hello, World!";
$ciphertext = $key->encryptData($plaintext);
```

--------------------------------

### getX509Certificate

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Retrieves the X.509 certificate associated with the key if applicable.

```APIDOC
## getX509Certificate()

### Description
Retrieves the X.509 certificate this key represents (if loaded from a certificate).

### Returns
- **string|null** - Certificate in PEM format, or null if not a certificate-based key.
```

--------------------------------

### Apply Strict Algorithm Policies

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/README.md

Restricts allowed algorithms for signatures and encryption to ensure high-security standards.

```php
// Signatures: only RSA-SHA-256
$sig->allowedSignatureAlgorithms = [XMLSecurityKey::RSA_SHA256];
$sig->allowedDigestAlgorithms = [XMLSecurityDSig::SHA256];

// Encryption: RSA-OAEP + AES-GCM only
$enc->allowedKeyAlgorithms = [XMLSecurityKey::RSA_OAEP];
$enc->allowedDataAlgorithms = [XMLSecurityKey::AES256_GCM];
```

--------------------------------

### XMLSecurityKey::convertRSA

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Converts raw RSA modulus and exponent into PEM format.

```APIDOC
## XMLSecurityKey::convertRSA(string $modulus, string $exponent)

### Description
Converts raw RSA modulus and exponent into PEM format.

### Parameters
- **$modulus** (string) - Required - Base64-decoded modulus
- **$exponent** (string) - Required - Base64-decoded exponent

### Return Type
string — PEM-formatted public key.

### Throws
Exception on conversion failure (invalid or missing components).
```

--------------------------------

### Verify an XML Signature

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/README.md

Verify a document signature using a public key, including support for custom ID attributes like those used in SAML.

```php
$doc = new DOMDocument();
$doc->load('signed.xml');

$objKey = new XMLSecurityKey(XMLSecurityKey::RSA_SHA256, ['type' => 'public']);
$objKey->loadKey('/path/to/trusted-cert.pem', true, true);

$objDSig = new XMLSecurityDSig();
$objDSig->idKeys = ['wsu:Id']; // For SAML/WS-Security
$objDSig->idNS = ['wsu' => 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd'];

try {
    $validatedNodes = $objDSig->verifyDocument($objKey, $doc);
    // Operate ONLY on $validatedNodes from here on
} catch (Exception $e) {
    die('Signature verification failed: ' . $e->getMessage());
}
```

--------------------------------

### Generate Session Key

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/api-reference/XMLSecurityKey.md

Creates a random session key for symmetric encryption, which is automatically assigned to the key instance.

```php
$encKey = new XMLSecurityKey(XMLSecurityKey::AES256_GCM);
$sessionKey = $encKey->generateSessionKey();
// Key is now ready for encryption
```

--------------------------------

### Strict Verification Comparison

Source: https://github.com/robrichards/xmlseclibs/blob/master/_autodocs/errors.md

Verification methods return integers rather than booleans, requiring strict comparison against 1 to confirm success.

```php
// WRONG: Will succeed on error
if ($objDSig->verify($key)) { /* ... */ }

// CORRECT: Strictly compare
if ($objDSig->verify($key) === 1) { /* ... */ }
```
Tokens:
Raw