xml-crypto

https://github.com/node-saml/xml-crypto
Admin
xml-crypto is a Node.js library for signing XML documents and verifying XML digital signatures, with...
Tokens:73,802
Snippets:436
Trust Score:5.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install xmldom and xpath

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Install the required DOM parser and XPath libraries for parsing and selecting XML nodes in the verification examples.

```shell
npm install @xmldom/xmldom xpath
```

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

### Private key PEM example

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Shows the beginning of a PEM-encoded private key file (key.pem) used for signing XML. Only the start of the key content is displayed.

```text
-----BEGIN PRIVATE KEY-----
MIICdwIBADANBgkqhkiG9w0...
-----END PRIVATE KEY-----
```

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

### Public certificate PEM example

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Shows the beginning of a PEM-encoded public certificate file (key_public.pem) used for verification. Only the start of the certificate content is displayed.

```text
-----BEGIN CERTIFICATE-----
MIIBxDCCAW6gAwIBAgIQxUSX...
-----END CERTIFICATE-----
```

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

### Usage example (module-level stable API)

Source: https://github.com/node-saml/xml-crypto

Shows how to require the stable public API from the xml-crypto module.

```javascript
const { SignedXml, C14nCanonicalization, ExclusiveCanonicalization, toPem, pemCertificates } =
  require("xml-crypto");
```

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

### SignedXml.getKeyInfoContent usage example

Source: https://github.com/node-saml/xml-crypto

Example of calling getKeyInfoContent with a PEM certificate and a prefix. The output shows the generated XML with the prefix applied.

```javascript
const SignedXml = require("xml-crypto").SignedXml;
const content = SignedXml.getKeyInfoContent({ publicCert: certPem, prefix: "foo" });
// '<foo:X509Data><foo:X509Certificate>...</foo:X509Certificate></foo:X509Data>'
```

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

### Run tests with npm test

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Executes the project's test suite using Mocha and Chai. Run from the project root after installing dependencies.

```shell
npm test
```

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

### Create SignedXml with publicCert and custom getCertFromKeyInfo

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use this constructor to verify a signature with a specific public certificate. The getCertFromKeyInfo function is called first to determine the certificate; if it returns null, publicCert is used. This example forces the use of publicCert by returning null.

```javascript
new SignedXml({
  publicCert: client_public_pem,
  getCertFromKeyInfo: () => null,
});
```

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

### computeSignatureAsync usage example

Source: https://github.com/node-saml/xml-crypto

Shows how to sign an XML document asynchronously. Requires a privateKey and signatureAlgorithm, adds a reference with an enveloped-signature transform, then awaits computeSignatureAsync.

```javascript
const sig = new SignedXml({ privateKey, signatureAlgorithm });
sig.addReference({ xpath: "//*[local-name(.)='book']", transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"], digestAlgorithm: "..." });
await sig.computeSignatureAsync(xml);
```

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

### Resulting signed XML document

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

The output of the signing example: the original library XML with the book element given an Id attribute, followed by a Signature element containing SignedInfo, SignatureValue, and optionally KeyInfo if a public certificate is provided.

```xml
<library>
  <book Id="_0">
    <name>Harry Potter</name>
  </book>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
      <SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
      <Reference URI="#_0">
        <Transforms>
          <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
        </Transforms>
        <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
        <DigestValue>9d/ciWlVZkaJnJ3KBB5WY1H2Y8WRXPB2DquM0goT8jY=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>uxmxGw2O3B6ylkhEXOaZ...[long base64 removed]...</SignatureValue>
  </Signature>
</library>
```

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

### C14nCanonicalization usage example

Source: https://github.com/node-saml/xml-crypto

Example of using `C14nCanonicalization` from the `xml-crypto` package. Creates an instance and calls `process` with a node and options containing `ancestorNamespaces`.

```JavaScript
const { C14nCanonicalization } = require("xml-crypto");
const c14n = new C14nCanonicalization();
const canon = c14n.process(node, { ancestorNamespaces: [] });
```

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

### Add a prefix to the signature with computeSignature prefix option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use the `prefix` option when calling `computeSignature` to add a prefix to the signature. The example signs a book element with an RSA-SHA256 signature and a SHA256 digest.

```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
});
sig.addReference({
  xpath: "//*[local-name(.)='book']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});
sig.computeSignature(xml, {
  prefix: "ds",
});
```

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

### Custom Signature Algorithm Registration

Source: https://github.com/node-saml/xml-crypto

Example showing how to register a custom signature algorithm implementing the SignatureAlgorithm interface on SignedXml.SignatureAlgorithms.

```APIDOC
## Usage — registering a custom signature algorithm

### Description
Example showing how to register a custom signature algorithm implementing the SignatureAlgorithm interface on SignedXml.SignatureAlgorithms.

### Example

```js
const SignedXml = require("xml-crypto").SignedXml;
const sig = new SignedXml();

// Register a custom algorithm implementing SignatureAlgorithm
sig.SignatureAlgorithms["urn:my:algo"] = class {
  getSignature(signedInfo, privateKey) {
    const crypto = require("crypto");
    return crypto.createSign("RSA-SHA256").update(signedInfo).sign(privateKey, "base64");
  }
  verifySignature(material, key, signatureValue) {
    return crypto.createVerify("RSA-SHA256").update(material).verify(key, signatureValue, "base64");
  }
  getAlgorithmName() { return "urn:my:algo"; }
};
```
```

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

### ExclusiveCanonicalization usage example

Source: https://github.com/node-saml/xml-crypto

Example of using ExclusiveCanonicalization with inclusiveNamespacesPrefixList option.

```js
const { ExclusiveCanonicalization } = require("xml-crypto");
const exc = new ExclusiveCanonicalization();
const canon = exc.process(node, { inclusiveNamespacesPrefixList: ["ds"] });
```

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

### Add custom Objects to the signature with SignedXml objects option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use the `objects` option when creating a SignedXml instance to add custom Objects to the signature. The example adds an Object with content and attributes, then references it via XPath and writes the signed XML to `signed.xml`.

```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  objects: [
    {
      content: "<TestObject>Test data in Object</TestObject>",
      attributes: {
        Id: "Object1",
        MimeType: "text/xml",
      },
    },
  ],
});

// Add a reference to the Object element
sig.addReference({
  xpath: "//*[@Id='Object1']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});

sig.computeSignature(xml);
fs.writeFileSync("signed.xml", sig.getSignedXml());
```

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

### computeSignature usage example

Source: https://github.com/node-saml/xml-crypto

Creates a SignedXml instance with an RSA-SHA256 signature algorithm, adds a reference to the book element with an enveloped-signature transform and SHA-256 digest, then computes the signature before the root element and logs the signed XML. Requires privateKey, signatureAlgorithm, and canonicalizationAlgorithm to be set.

```javascript
const sig = new SignedXml({ privateKey, signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" });
sig.addReference({ xpath: "//*[local-name(.)='book']", transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"], digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256" });
sig.computeSignature(xml, { location: { reference: "/*", action: "before" } });
console.log(sig.getSignedXml());
```

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

### Sign XML asynchronously with computeSignatureAsync

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Signs an XML document asynchronously using the custom AsyncRsaSha256 algorithm. The algorithm is registered under the RSA-SHA256 URI, and computeSignatureAsync() returns a promise that resolves with the SignedXml instance. The example signs a simple library XML and writes the signed document to signed.xml.

```javascript
async function sign(xml) {
  const sig = new SignedXml({
    privateKey: fs.readFileSync("client.pem"),
    canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
    signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  });
  sig.SignatureAlgorithms["http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"] = AsyncRsaSha256;
  sig.addReference({
    xpath: "//*[local-name(.)='book']",
    digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
    transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
  });

  await sig.computeSignatureAsync(xml);
  return sig;
}

sign("<library><book><name>Harry Potter</name></book></library>").then((sig) =>
  fs.writeFileSync("signed.xml", sig.getSignedXml()),
);
```

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

### Specify signature location with computeSignature location option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use the `location` option when calling `computeSignature` to move the signature. Set `reference` to an XPath expression selecting a node (default `/*`) and `action` to `append` (default), `prepend`, `before`, or `after`. This example places the signature after the book element.

```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
});
sig.addReference({
  xpath: "//*[local-name(.)='book']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});
sig.computeSignature(xml, {
  location: { reference: "//*[local-name(.)='book']", action: "after" }, // This will place the signature after the book element
});
```

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

### Usage example of createOptionalCallbackFunction

Source: https://github.com/node-saml/xml-crypto

Shows the pattern the library itself uses. The returned function can be called synchronously (returns T) or with a trailing error-first callback. In the callback form, the result is delivered via callback(null, result) or callback(err) on a thrown error.

```ts
import { createOptionalCallbackFunction } from "xml-crypto";

const add = createOptionalCallbackFunction((a: number, b: number) => a + b);

add(2, 3);                    // 5  (synchronous)
add(2, 3, (err, res) => {     // callback form
  if (err) { /* ... */ }
  console.log(res);           // 5
});
```

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

### addReference usage example

Source: https://github.com/node-saml/xml-crypto

Creates a SignedXml instance and adds a reference with an XPath selecting book elements, an enveloped-signature transform, and SHA-256 digest. The reference's getValidatedNode throws if checkSignature() was not called.

```javascript
const SignedXml = require("xml-crypto").SignedXml;
const sig = new SignedXml({ privateKey, signatureAlgorithm });
sig.addReference({ xpath: "//*[local-name(.)='book']", transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"], digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256" });
```

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

### checkSignature usage example

Source: https://github.com/node-saml/xml-crypto

Verifies a signature using a public certificate. Returns true on success or throws an Error with message 'invalid signature: the signature value ... is incorrect' when verification fails. Requires publicCert or KeyInfo/privateKey to be set.

```javascript
const sig = new SignedXml({ publicCert: certPem });
sig.loadSignature(signatureNode);
const isValid = sig.checkSignature(xml); // true / throws on bad value
try {
  const ok = sig.checkSignature(xml);
} catch (e) {
  // invalid signature: the signature value ... is incorrect
}
```

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

### Verify with implicitTransforms option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use this when verification fails due to hidden implicit transforms. The implicitTransforms array specifies canonicalization transforms to apply after the Reference transforms. This example uses exclusive canonicalization.

```javascript
const sig = new SignedXml({
  implicitTransforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
  publicCert: fs.readFileSync("client_public.pem"),
});
sig.loadSignature(signature);
const res = sig.checkSignature(xml);
```

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

### Register custom hash algorithm via SignedXml.HashAlgorithms

Source: https://github.com/node-saml/xml-crypto

Shows how to register a custom hash algorithm on the SignedXml.HashAlgorithms registry using a custom URI. The example registers a SHA-256 implementation under "urn:my:sha-256". Unlike HMAC signing, built-in SHA digest classes are always registered.

```JavaScript
const SignedXml = require("xml-crypto").SignedXml;
const sig = new SignedXml();

// Register a custom hash algorithm via the registry:
sig.HashAlgorithms["urn:my:sha-256"] = class implements /* HashAlgorithm */ {
  getAlgorithmName() { return "urn:my:sha-256"; }
  getHash(xml) {
    const crypto = require("crypto");
    return crypto.createHash("sha256").update(xml).digest("base64");
  }
};
```

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

### Sign an XML document with SignedXml

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Creates a SignedXml instance with a private key, canonicalization and signature algorithms, adds a reference to the 'book' element, computes the signature, and writes the signed XML to a file. Requires a private key file 'client.pem'.

```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
});
sig.addReference({
  xpath: "//*[local-name(.)='book']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});
sig.computeSignature(xml);
fs.writeFileSync("signed.xml", sig.getSignedXml());
```

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

### Migrate callback-based algorithm to Async methods

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Shows how to convert an algorithm that uses callbacks to one that returns promises from Async methods. The before version uses getSignature() and verifySignature() with callbacks, while the after version uses getSignatureAsync() and verifySignatureAsync() returning promises. The after version also calls computeSignatureAsync() with await.

```javascript
// Before
class AsyncRsaSha256 {
  getSignature(signedInfo, privateKey, callback) {
    signingServer.sign(signedInfo, callback);
  }

  verifySignature(material, key, signatureValue, callback) {
    signingServer.verify(material, signatureValue, callback);
  }
}

sig.computeSignature(xml, (err) => {
  if (err) {
    throw err;
  }
  fs.writeFileSync("signed.xml", sig.getSignedXml());
});

// After
class AsyncRsaSha256 {
  getSignatureAsync(signedInfo, privateKey) {
    return signingServer.sign(signedInfo);
  }

  verifySignatureAsync(material, key, signatureValue) {
    return signingServer.verify(material, signatureValue);
  }
}

await sig.computeSignatureAsync(xml);
fs.writeFileSync("signed.xml", sig.getSignedXml());
```

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

### Using toPem, pemCertificates, and findAncestorNs

Source: https://github.com/node-saml/xml-crypto

Shows how to import and use the utility functions from the xml-crypto package. pemCertificates extracts base64 certificate data from a PEM string, toPem converts a certificate buffer to a canonical PEM string, and findAncestorNs finds the namespace of an ancestor element.

```javascript
const { toPem, pemCertificates, findAncestorNs } = require("xml-crypto");

const certs = pemCertificates(pem);          // string[] of base64 cert data
const pem = toPem(certBuffer, "CERTIFICATE"); // canonical PEM string
const ns = findAncestorNs(doc, "//*[local-name(.)='book']");
```

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

### Sha512

Source: https://github.com/node-saml/xml-crypto

SHA-512 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-512 digest of an XML string.

```APIDOC
## Sha512

### Description
SHA-512 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-512 digest of an XML string.

### Methods

#### getHash

- **Signature**: `getHash(xml: string): string`
- **Description**: SHA-512 of the XML string, base64 digest.

#### getAlgorithmName

- **Signature**: `(): string`
- **Description**: Returns `http://www.w3.org/2001/04/xmlenc#sha512`
```

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

### Sha256

Source: https://github.com/node-saml/xml-crypto

SHA-256 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-256 digest of an XML string.

```APIDOC
## Sha256

### Description
SHA-256 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-256 digest of an XML string.

### Methods

#### getHash

- **Signature**: `getHash(xml: string): string`
- **Description**: SHA-256 of the XML string, base64 digest.

#### getAlgorithmName

- **Signature**: `(): string`
- **Description**: Returns `http://www.w3.org/2001/04/xmlenc#sha256`
```

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

### new SignedXml(options)

Source: https://github.com/node-saml/xml-crypto

Creates a new SignedXml instance with the provided constructor options. The options configure signing and verification behavior, including keys, algorithms, and KeyInfo handling.

```APIDOC
## new SignedXml(options)

### Description
Creates a new SignedXml instance with the provided constructor options. The options configure signing and verification behavior, including keys, algorithms, and KeyInfo handling.

### Constructor Options
- `privateKey` (crypto.KeyLike) - Optional - Buffer/PEM string of the private key. Required to compute a signature.
- `publicCert` (crypto.KeyLike) - Optional - Public certificate/pubkey, published in `KeyInfo` and usable to verify.
- `signatureAlgorithm` (SignatureAlgorithmType) - Optional - Signature algorithm URI resolved against `SignatureAlgorithms`. Required to compute/verify signatures.
- `canonicalizationAlgorithm` (CanonicalizationAlgorithmType) - Optional - Canonicalization URI resolved against `CanonicalizationAlgorithms`. Required to compute/verify signatures.
- `idMode` ("wssecurity") - Optional - When set, ID attributes are found/written as `wsu:Id` in the WS-Security utility namespace instead of `Id/ID/id`.
- `idAttribute` (string) - Optional - Attribute name prepended to the ID lookup list (base list `["Id","ID","id"]`).
- `inclusiveNamespacesPrefixList` (string | string[]) - Optional - Prefixes treated as "inclusive" during canonicalization. A string is split on a single space.
- `implicitTransforms` (ReadonlyArray<CanonicalizationOrTransformAlgorithmType>) - Optional - Transforms added implicitly (appended) to every reference.
- `keyInfoAttributes` (Record<string, string>) - Optional - Extra attributes written onto the generated `KeyInfo` element.
- `getKeyInfoContent` ((args?: GetKeyInfoContentArgs) => string | null) - Optional - Builds the `KeyInfo` child content XML string (or `null` to omit).
- `getCertFromKeyInfo` ((keyInfo?: Node | null) => string | null) - Optional - Extracts the signing certificate from a `KeyInfo` node.
- `objects` (Array<{ content: string; attributes?: ObjectAttributes }>) - Optional - `Object` elements to include in the signature.

### Behavioral Defaults
- `signatureAlgorithm`, `inclusiveNamespacesPrefixList`, `implicitTransforms`, `keyInfoAttributes` fall back to the instance-default field values when not supplied.
- `getCertFromKeyInfo` falls back to `SignedXml.noop` (returns `null`).
- `getKeyInfoContent` defaults to the static `SignedXml.getKeyInfoContent`.
```

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

### new SignedXml(options?)

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Constructs a SignedXml object for signing and verifying XML documents. The options object configures signing, verification, and key handling behavior.

```APIDOC
## [CONSTRUCTOR] new SignedXml(options?)

### Description
Constructs a SignedXml object for signing and verifying XML documents. The options object configures signing, verification, and key handling behavior.

### Constructor
`new SignedXml(options?: SignedXmlOptions)`

### Parameters
#### Options
- `idMode` (string) - Optional - If the value of `wssecurity` is passed it will create/validate id's with the ws-security namespace.
- `idAttribute` (string) - Optional - The name of an additional attribute that holds an element's id; it is checked before `Id`, `ID` and `id`.
- `privateKey` (string or Buffer) - Optional - The private key to use for signing.
- `publicCert` (string or Buffer) - Optional - The public certificate to use for verifying.
- `signatureAlgorithm` (string) - Optional - The signature algorithm to use.
- `canonicalizationAlgorithm` (string) - Optional - The canonicalization algorithm to use.
- `inclusiveNamespacesPrefixList` (string) - Optional - A list of namespace prefixes to include during canonicalization.
- `implicitTransforms` (string[]) - Optional - A list of implicit transforms to use during verification.
- `keyInfoAttributes` (object) - Optional - A hash of attributes and values `attrName: value` to add to the KeyInfo node.
- `getKeyInfoContent` (function) - Optional - A function that returns the content of the KeyInfo node.
- `getCertFromKeyInfo` (function) - Optional - A function that returns the certificate from the `<KeyInfo />` node.
```

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

### Sha1

Source: https://github.com/node-saml/xml-crypto

SHA-1 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-1 digest of an XML string.

```APIDOC
## Sha1

### Description
SHA-1 hash algorithm implementation. Provides methods to get the algorithm name and compute a base64-encoded SHA-1 digest of an XML string.

### Methods

#### getHash

- **Signature**: `getHash(xml: string): string`
- **Description**: SHA-1 of the XML string, base64-encoded digest.

#### getAlgorithmName

- **Signature**: `(): string`
- **Description**: Returns `http://www.w3.org/2000/09/xmldsig#sha1`
```

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

### Sign XML with custom algorithms

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Registers custom algorithms on a SignedXml instance and signs an XML document, writing the result to a file.

```javascript
function signXml(xml, xpath, key, dest) {
  const sig = new SignedXml({
    publicCert: fs.readFileSync("my_public_cert.pem", "latin1"),
    privateKey: fs.readFileSync(key),
    // Configure the signature object to use the custom algorithms.
    signatureAlgorithm: "http://mySigningAlgorithm",
    canonicalizationAlgorithm: "http://myCanonicalization",
  });

  // Register all the custom algorithms.
  sig.CanonicalizationAlgorithms["http://myTransformation"] = MyTransformation;
  sig.CanonicalizationAlgorithms["http://myCanonicalization"] = MyCanonicalization;
  sig.HashAlgorithms["http://myDigestAlgorithm"] = MyDigest;
  sig.SignatureAlgorithms["http://mySigningAlgorithm"] = MySignatureAlgorithm;

  sig.addReference({
    xpath,
    transforms: ["http://myTransformation"],
    digestAlgorithm: "http://myDigestAlgorithm",
  });
  sig.computeSignature(xml);
  fs.writeFileSync(dest, sig.getSignedXml());
}

const xml = "<library><book><name>Harry Potter</name></book></library>";

signXml(xml, "//*[local-name(.)='book']", "client.pem", "result.xml");
```

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

### constructor(options?: SignedXmlOptions)

Source: https://github.com/node-saml/xml-crypto

Creates a new SignedXml instance for signing and verifying XML documents according to the W3C XML Signature specification. Accepts optional configuration options.

```APIDOC
## constructor(options?: SignedXmlOptions)

### Description
Creates a new SignedXml instance for signing and verifying XML documents according to the W3C XML Signature specification. Accepts optional configuration options.

### Parameters
- `options` (SignedXmlOptions) - Optional - Configuration for signing/verify; see configuration.md.

### Example
```js
const { SignedXml } = require("xml-crypto");
const signedXml = new SignedXml();
```
```

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

### Using getSignature with sync and callback styles

Source: https://github.com/node-saml/xml-crypto

Shows how built-in SignatureAlgorithm methods (getSignature, verifySignature) are wired through the factory. The sync call returns a string; the callback form is deprecated and delivers the result via callback.

```js
const SignedXml = require("xml-crypto").SignedXml;
const algo = new SignedXml().SignatureAlgorithms["http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"];

const value = algo.getSignature(signedInfoBytes, pemKey); // sync -> string
// callback form (deprecated):
algo.getSignature(signedInfoBytes, pemKey, (err, result) => {
  if (err) return console.error(err);
  console.log(result);
});
```

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

### Instance Properties

Source: https://github.com/node-saml/xml-crypto

Runtime configuration via instance properties. These properties can be set directly on the SignedXml instance between construction and use.

```APIDOC
## Instance Properties

### Description
Runtime configuration via instance properties. These properties can be set directly on the SignedXml instance between construction and use.

### Properties
- `privateKey` - The private key used for signing.
- `publicCert` - The public certificate used for verification.
- `signatureAlgorithm` - The signature algorithm URI.
- `canonicalizationAlgorithm` - The canonicalization algorithm URI.
- `CanonicalizationAlgorithms` - The canonicalization algorithm registry.
- `HashAlgorithms` - The hash algorithm registry.
- `SignatureAlgorithms` - The signature algorithm registry.

### Methods
- `enableHMAC()` - Switches the instance to HMAC-only signing.
```

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

### computeSignature with prefix option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Demonstrates how to add a prefix to the signature by using the `prefix` option when calling `computeSignature`.

```APIDOC
## computeSignature(xml, options)

### Description
Adds a prefix to the signature by using the `prefix` option.

### Method
computeSignature

### Parameters
- **xml** (string) - Required - The XML string to sign.
- **options** (object) - Optional - An object containing the `prefix` option.
  - **prefix** (string) - Optional - The prefix to add to the signature.

### Request Example
```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
});
sig.addReference({
  xpath: "//*[local-name(.)='book']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});
sig.computeSignature(xml, {
  prefix: "ds",
});
```
```

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

### constructor()

Source: https://github.com/node-saml/xml-crypto

Creates a new EnvelopedSignature instance. No arguments are required; includeComments is always set to false.

```APIDOC
## Constructor

### Description
Creates a new EnvelopedSignature instance. No arguments are required; includeComments is always set to false.

### Method
constructor

### Parameters
None

### Response
No return value.
```

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

### Import modules for custom signing

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Imports the SignedXml class from xml-crypto and the fs module for file operations.

```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");
```

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

### SignedXml with objects option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Demonstrates how to add custom Objects to the signature using the `objects` option when creating a SignedXml instance.

```APIDOC
## new SignedXml(options)

### Description
Creates a SignedXml instance with custom Objects to add to the signature.

### Method
Constructor

### Parameters
- **options** (object) - Required - An object containing the `objects` option.
  - **objects** (array) - Optional - An array of objects to add to the signature.
    - **content** (string) - Required - The XML content of the object.
    - **attributes** (object) - Optional - Attributes for the object element.

### Request Example
```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  objects: [
    {
      content: "<TestObject>Test data in Object</TestObject>",
      attributes: {
        Id: "Object1",
        MimeType: "text/xml",
      },
    },
  ],
});

// Add a reference to the Object element
sig.addReference({
  xpath: "//*[@Id='Object1']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});

sig.computeSignature(xml);
fs.writeFileSync("signed.xml", sig.getSignedXml());
```
```

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

### Signed XML with KeyInfo containing X.509 certificate

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Shows the default KeyInfo output when publicCert contains an X.509 certificate: a KeyInfo element with X509Data and the certificate's base64 content.

```xml
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    ...[signature info removed]...
  </SignedInfo>
  <SignatureValue>uxmxGw2O3B6ylkhEXOaZ...[long base64 removed]...</SignatureValue>
  <KeyInfo>
    <X509Data>
      <X509Certificate>MIIGYjCCBJagACCBN...[long base64 removed]...</X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>
```

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

### computeSignature with location option

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Demonstrates how to specify the location of the signature by using the `location` option when calling `computeSignature`.

```APIDOC
## computeSignature(xml, options)

### Description
Moves the signature to a specified location using the `location` option.

### Method
computeSignature

### Parameters
- **xml** (string) - Required - The XML string to sign.
- **options** (object) - Optional - An object containing the `location` option.
  - **location** (object) - Optional - Specifies the location of the signature.
    - **reference** (string) - Optional - XPath expression that selects a node (default `/*`).
    - **action** (string) - Optional - One of `append`, `prepend`, `before`, `after`.

### Request Example
```javascript
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = "<library><book><name>Harry Potter</name></book></library>";

const sig = new SignedXml({
  privateKey: fs.readFileSync("client.pem"),
  canonicalizationAlgorithm: "http://www.w3.org/2001/10/xml-exc-c14n#",
  signatureAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
});
sig.addReference({
  xpath: "//*[local-name(.)='book']",
  digestAlgorithm: "http://www.w3.org/2001/04/xmlenc#sha256",
  transforms: ["http://www.w3.org/2001/10/xml-exc-c14n#"],
});
sig.computeSignature(xml, {
  location: { reference: "//*[local-name(.)='book']", action: "after" }, // This will place the signature after the book element
});
```
```

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

### Convert .pfx certificate to .pem using openssl

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Use this shell command to convert a .pfx certificate to .pem format. The resulting .pem can be used for signing; for validation, extract the CERTIFICATE block into a new .pem file.

```shell
openssl pkcs12 -in c:\certs\yourcert.pfx -out c:\certs\cag.pem
```

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

### toPem

Source: https://github.com/node-saml/xml-crypto

Converts a certificate buffer to a canonical PEM string with the specified label.

```APIDOC
## toPem

### Description
Converts a certificate buffer to a canonical PEM string with the specified label.

### Method
Function

### Signature
`toPem(certBuffer, label)`

### Parameters
- **certBuffer** (Buffer) - Required - The certificate data as a Buffer.
- **label** (string) - Required - The PEM label (e.g., "CERTIFICATE").

### Returns
- **string** - The canonical PEM string.

### Example
```js
const pem = toPem(certBuffer, "CERTIFICATE");
```
```

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

### Verify XML signature with xmldom and xpath

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Parses a signed XML file, selects the Signature element, loads it into SignedXml, and checks the signature. The comment warns against parsing untrusted data before verification. The signature is selected using XPath with the XMLDSIG namespace.

```javascript
const { DOMParser } = require("@xmldom/xmldom");
const xpath = require("xpath");
const { SignedXml } = require("xml-crypto");
const fs = require("fs");

const xml = fs.readFileSync("signed.xml", "utf8");
const doc = new DOMParser().parseFromString(xml, "text/xml");

// DO NOT attempt to parse whatever data object you have here in `doc`
// and then use it to verify the signature. This can lead to security issues.
// i.e. BAD: parseAssertion(doc),
// good: see below

const signature = xpath.select1(
  "//*[local-name(.)='Signature' and namespace-uri(.)='http://www.w3.org/2000/09/xmldsig#']",
  doc,
);
const sig = new SignedXml({ publicCert: fs.readFileSync("client_public.pem") });
sig.loadSignature(signature);
const res = sig.checkSignature(xml);
```

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

### Import SignedXml from xml-crypto

Source: https://github.com/node-saml/xml-crypto

Import the SignedXml class from the package entry point.

```javascript
const { SignedXml } = require("xml-crypto");
```

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

### toPem(value, pemLabel?): string

Source: https://github.com/node-saml/xml-crypto

Converts a PEM message, base64 data, or Buffer into canonical PEM format. Re-exported at the package entry.

```APIDOC
## toPem(value, pemLabel?): string

### Description
Converts a PEM message, base64 data, or Buffer into canonical PEM format. Re-exported at the package entry.

### Signature
```ts
export function toPem(value: string | Buffer, pemLabel?: PemLabel): string;
```

### Parameters
- **value** (string | Buffer) - Required - A PEM message (or several), base64 data (needs a label), or a Buffer (DER, or a PEM file's bytes if it begins with an opening boundary).
- **pemLabel** (PemLabel) - Optional (required when `value` is bare base64) - Label to give base64 data.

### Returns
- **string** - The value as canonical PEM (one message per certificate/key, wrapped at 64 chars).

### Throws
- **Error** - `Invalid PEM format.` for unreadable values; `A PEM label is required to wrap base64 data.` when base64 is passed with no label; `Invalid PEM label.` for an unusable label.
```

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

### Re-export stable PEM and namespace helpers from utils

Source: https://github.com/node-saml/xml-crypto

Only the stable PEM and namespace helpers are re-exported at the entry point by name. Other utils helpers are deprecated and slated for removal in v7.0.

```typescript
export { findAncestorNs, normalizePem, pemCertificates, pemToDer, toPem } from "./utils";
```

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

### Custom canonicalization algorithm class

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Defines a custom canonicalization algorithm, similar to transformation but applied on SignedInfo.

```javascript
class MyCanonicalization {
  // Given a node (from the xmldom module), return its canonical representation as a string.
  process(node) {
    // You should apply your canonicalization before returning.
    return node.toString();
  }

  getAlgorithmName() {
    return "http://myCanonicalization";
  }
}
```

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

### Define AsyncRsaSha256 algorithm with getSignatureAsync and verifySignatureAsync

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Defines a custom signature algorithm class that implements asynchronous signing and verification by returning promises from getSignatureAsync() and verifySignatureAsync(). The getAlgorithmName() method returns the URI for RSA-SHA256, which is used as the SignatureMethod. This class is registered on the SignedXml instance under that URI.

```javascript
const { SignedXml } = require("xml-crypto");
const crypto = require("crypto");
const fs = require("fs");

class AsyncRsaSha256 {
  async getSignatureAsync(signedInfo, privateKey) {
    // Do some asynchronous things here, such as calling a signing server.
    const signer = crypto.createSign("RSA-SHA256");
    signer.update(signedInfo);
    return signer.sign(privateKey, "base64");
  }

  async verifySignatureAsync(material, key, signatureValue) {
    // Do some asynchronous things here, too.
    const verifier = crypto.createVerify("RSA-SHA256");
    verifier.update(material);
    return verifier.verify(key, signatureValue, "base64");
  }

  getAlgorithmName() {
    return "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256";
  }
}
```

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

### Migrate from callback form to promise-based computeSignature

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Shows the deprecated callback form of computeSignature() and the recommended promise-based form for algorithms that return their answer directly. The callback form prints a DeprecationWarning and will be removed in 7.0. The after version calls computeSignature() without a callback and writes the signed XML immediately.

```javascript
// Before
sig.computeSignature(xml, (err) => {
  if (err) {
    throw err;
  }
  fs.writeFileSync("signed.xml", sig.getSignedXml());
});

// After
sig.computeSignature(xml);
fs.writeFileSync("signed.xml", sig.getSignedXml());
```

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

### Custom transformation algorithm class

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Defines a custom transformation algorithm by implementing process and getAlgorithmName methods.

```javascript
class MyTransformation {
  // Given a node (from the xmldom module), return its canonical representation as a string.
  process(node) {
    // You should apply your transformation before returning.
    return node.toString();
  }

  getAlgorithmName() {
    return "http://myTransformation";
  }
}
```

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

### computeSignature(xml, [options])

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Computes the signature for the given XML document. The options object allows customization of the signature prefix, attributes, location, and existing namespaces.

```APIDOC
## [METHOD] computeSignature(xml, [options])

### Description
Computes the signature for the given XML document. The options object allows customization of the signature prefix, attributes, location, and existing namespaces.

### Method
`computeSignature(xml, [options])`

### Parameters
#### Request Body
- `xml` (string) - Required - A string containing a xml document.
- `options` (object) - Optional - An object with the following properties:
  - `prefix` (string) - Optional - Adds this value as a prefix for the generated signature tags.
  - `attrs` (object) - Optional - A hash of attributes and values `attrName: value` to add to the signature root node.
  - `location` (object) - Optional - Customize the location of the signature. Pass an object with a `reference` key (XPath expression to a reference node) and an `action` key (one of: `append`, `prepend`, `before`, `after`).
  - `existingPrefixes` (object) - Optional - A hash of prefixes and namespaces `prefix: namespace` that shouldn't be in the signature because they already exist in the xml.
```

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

### loadSignature(signatureXml)

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Loads a signature from the provided XML string or node object so it can be verified. The signatureXml parameter accepts a string or an xmldom node containing the XML representation of the signature.

```APIDOC
## loadSignature(signatureXml)

### Description
Loads the signature from the given XML representation so it can be verified.

### Method
loadSignature

### Parameters
- **signatureXml** (string | node) - Required - A string or node object (like an xmldom node) containing the XML representation of the signature.

### Response
No return value documented.
```

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

### Direct instantiation of EnvelopedSignature

Source: https://github.com/node-saml/xml-crypto

Shows direct instantiation via deep import. Requires importing from the built lib/enveloped-signature.js module since it is not re-exported at the package entry point.

```javascript
const { EnvelopedSignature } = require("xml-crypto"); // via deep import
const transform = new EnvelopedSignature();
transform.getAlgorithmName();
// => "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
signature.parentNode && signature.parentNode.removeChild(signature);
```

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

### SignatureAlgorithm.getSignatureAsync(signedInfo, privateKey)

Source: https://github.com/node-saml/xml-crypto/blob/master/README.md

Asynchronously generates a signature for the given signed info using the private key. This method is used by computeSignatureAsync() and should return a Promise that resolves with the signature value.

```APIDOC
## [ASYNC] getSignatureAsync(signedInfo, privateKey)

### Description
Asynchronously generates a signature for the given signed info using the private key. This method is used by computeSignatureAsync() and should return a Promise that resolves with the signature value.

### Method
ASYNC

### Parameters
#### Parameters
- **signedInfo** (string) - Required - The canonicalized signed info to sign.
- **privateKey** (string) - Required - The private key used for signing.

### Response
#### Success Response
- **string** - The signature value in base64 encoding.

### Request Example
```javascript
async getSignatureAsync(signedInfo, privateKey) {
  // Do some asynchronous things here, such as calling a signing server.
  const signer = crypto.createSign("RSA-SHA256");
  signer.update(signedInfo);
  return signer.sign(privateKey, "base64");
}
```

### Response Example
```javascript
// Returns a Promise that resolves with the signature value
```
```

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

### SignedXml.noop static property

Source: https://github.com/node-saml/xml-crypto

No-op function used as a fallback for getCertFromKeyInfo and getKeyInfoContent.

```typescript
static noop = () => null;
```
Tokens:
Raw