diff --git a/README.md b/README.md index c162ab8..2d33b85 100644 --- a/README.md +++ b/README.md @@ -365,6 +365,8 @@ To verify xml documents: - `loadSignature(signatureXml)` - loads the signature where: - `signatureXml` - a string or node object (like an [xmldom](https://github.com/xmldom/xmldom) node) containing the xml representation of the signature - `checkSignature(xml)` - validates the given xml document and returns `true` if the validation was successful +- `getSignedReferences()` - returns the canonical XML of each reference, only after `checkSignature` succeeds +- `validateElementAgainstReferences(elemOrXpath, doc)` - **[deprecated]** after `checkSignature` succeeds, use the XML that `getSignedReferences()` returns instead of nodes from the original document ## Customizing Algorithms diff --git a/src/signed-xml.ts b/src/signed-xml.ts index 3493f9c..e1116e8 100644 --- a/src/signed-xml.ts +++ b/src/signed-xml.ts @@ -44,6 +44,12 @@ const warnOriginalXmlWithIds = deprecate( "XML_CRYPTO_GET_ORIGINAL_XML_WITH_IDS", ); +const warnValidateElementAgainstReferences = deprecate( + () => {}, + "`validateElementAgainstReferences()` is deprecated and will be removed in a future version. After `checkSignature()` succeeds, use the XML that `getSignedReferences()` returns instead of nodes from the original document.", + "XML_CRYPTO_VALIDATE_ELEMENT_AGAINST_REFERENCES", +); + export class SignedXml { idMode?: "wssecurity"; idAttributes: string[]; @@ -503,7 +509,12 @@ export class SignedXml { } } + /** + * @deprecated Will be removed in a future version. After {@link checkSignature} succeeds, use + * the XML that {@link getSignedReferences} returns instead of nodes from the original document. + */ validateElementAgainstReferences(elemOrXpath: Element | string, doc: Document): Reference { + warnValidateElementAgainstReferences(); let elem: Element; if (typeof elemOrXpath === "string") { const firstElem = xpath.select1(elemOrXpath, doc); diff --git a/test/signature-unit-tests.spec.ts b/test/signature-unit-tests.spec.ts index 2ce3ced..2545176 100644 --- a/test/signature-unit-tests.spec.ts +++ b/test/signature-unit-tests.spec.ts @@ -911,6 +911,7 @@ describe("Signature unit tests", function () { const firstGrandchild = doc.firstChild?.firstChild; isDomNode.assertIsElementNode(firstGrandchild); + /* eslint-disable-next-line deprecation/deprecation */ const matchedReference = sig.validateElementAgainstReferences(firstGrandchild, doc); expect(matchedReference).to.not.be.false;