{"id":18601576,"url":"https://github.com/peculiarventures/xmldsigjs","last_synced_at":"2025-05-08T04:38:39.113Z","repository":{"id":14647647,"uuid":"71070021","full_name":"PeculiarVentures/xmldsigjs","owner":"PeculiarVentures","description":"XMLDSIGjs provides an implementation of XMLDSIG in Typescript/Javascript based on WebCrypto","archived":false,"fork":false,"pushed_at":"2023-01-09T22:46:21.000Z","size":1555,"stargazers_count":39,"open_issues_count":29,"forks_count":29,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-14T23:15:41.861Z","etag":null,"topics":["javascript","node-webcrypto-ossl","soap","typescript","web-crypto","webcrypto","webservices","xmldsig","xmldsig-signature"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PeculiarVentures.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-16T18:48:11.000Z","updated_at":"2024-04-13T21:11:54.000Z","dependencies_parsed_at":"2023-01-13T18:02:54.716Z","dependency_job_id":null,"html_url":"https://github.com/PeculiarVentures/xmldsigjs","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeculiarVentures%2Fxmldsigjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeculiarVentures%2Fxmldsigjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeculiarVentures%2Fxmldsigjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeculiarVentures%2Fxmldsigjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PeculiarVentures","download_url":"https://codeload.github.com/PeculiarVentures/xmldsigjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231474812,"owners_count":18382160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","node-webcrypto-ossl","soap","typescript","web-crypto","webcrypto","webservices","xmldsig","xmldsig-signature"],"created_at":"2024-11-07T02:08:45.503Z","updated_at":"2024-12-27T11:14:18.995Z","avatar_url":"https://github.com/PeculiarVentures.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XMLDSIGjs\n\n[![license](https://img.shields.io/badge/license-MIT-green.svg?style=flat)](https://raw.githubusercontent.com/PeculiarVentures/xmldsigjs/master/LICENSE) [![CircleCI](https://circleci.com/gh/PeculiarVentures/xmldsigjs.svg?style=svg)](https://circleci.com/gh/PeculiarVentures/xmldsigjs)\n[![Coverage Status](https://coveralls.io/repos/github/PeculiarVentures/xmldsigjs/badge.svg?branch=master)](https://coveralls.io/github/PeculiarVentures/xmldsigjs?branch=master)\n[![npm version](https://badge.fury.io/js/xmldsigjs.svg)](https://badge.fury.io/js/xmldsigjs)\n\n[![NPM](https://nodei.co/npm/xmldsigjs.png)](https://nodei.co/npm/xmldsigjs/)\n\n[XMLDSIG](https://en.wikipedia.org/wiki/XML_Signature) is short for \"XML Digital Signature\". This library aims to provide an implementation of XMLDSIG in Typescript/Javascript that uses Web Crypto for cryptographic operations so it can be used both in browsers and in Node.js (when used with a polyfill like [node-webcrypto-ossl](https://github.com/PeculiarVentures/node-webcrypto-ossl) or [node-webcrypto-p11](https://github.com/PeculiarVentures/node-webcrypto-p11)).\n\n## INSTALLING\n\n```\nnpm install xmldsigjs\n```\n\nThe npm module has `build` folder with the following files:\n\n| Name            | Size   | Description                                    |\n|-----------------|--------|------------------------------------------------|\n| index.js        | 105 Kb | CJS module with external modules               | \n| index.es.js     | 100 Kb | ES module with external modules                | \n| xmldsig.js      | 872 Kb | IIFE bundle module                             | \n| xmldsig.min.js  | 398 Kb | minified IIFE bundled module                   |\n \n## COMPATABILITY\n\n### CRYPTOGRAPHIC ALGORITHM SUPPORT \n\n|                   | SHA1 | SHA2-256 | SHA2-384 | SHA2-512 |\n|-------------------|------|----------|----------|----------|\n| RSASSA-PKCS1-v1_5 | X    | X        | X        | X        |\n| RSA-PSS           | X    | X        | X        | X        |\n| ECDSA             | X    | X        | X        | X        |\n| HMAC              | X    | X        | X        | X        |\n\n### CANONICALIZATION ALGORITHM SUPPORT\n\n- XmlDsigC14NTransform\n- XmlDsigC14NWithCommentsTransform\n- XmlDsigExcC14NTransform\n- XmlDsigExcC14NWithCommentsTransform\n- XmlDsigEnvelopedSignatureTransform\n- XmlDsigBase64Transform\n\n\n### PLATFORM SUPPORT\n\nXMLDSIGjs works with any browser that supports Web Crypto. Since node does not have Web Crypto you will need a polyfill on this platform, for this reason the npm package includes [node-webcrypto-ossl](https://github.com/PeculiarVentures/node-webcrypto-ossl); browsers do not need this dependency and in those cases though it will be installed it will be ignored.\n\nIf you need to use a Hardware Security Module we have also created a polyfill for Web Crypto that supports PKCS #11. Our polyfill for this is [node-webcrypto-p11](https://github.com/PeculiarVentures/node-webcrypto-p11).\n\nTo use [node-webcrypto-ossl](https://github.com/PeculiarVentures/node-webcrypto-ossl) you need to specify you want to use it, that looks like this:\n\n```javascript\nvar xmldsigjs = require(\"xmldsigjs\");\nvar WebCrypto = require(\"node-webcrypto-ossl\");\n\nxmldsigjs.Application.setEngine(\"OpenSSL\", new WebCrypto());\n```\n\nThe [node-webcrypto-p11](https://github.com/PeculiarVentures/node-webcrypto-p11) polyfill will work the same way. The only difference is that you have to specify the details about your PKCS#11 device when you instansiate it:\n\n```javascript\nvar xmldsigjs = require(\"xmldsigjs\");\nvar WebCrypto = require(\"node-webcrypto-p11\");\n\nxmldsigjs.Application.setEngine(\"PKCS11\", new WebCrypto({\n    library: \"/path/to/pkcs11.so\",\n\tname: \"Name of PKCS11 lib\",\n\tslot: 0,\n    sessionFlags: 4, // SERIAL_SESSION\n\tpin: \"token pin\"\n}));\n```\n\n## WARNING\n\n**Using XMLDSIG is a bit like running with scissors so use it cautiously. That said it is needed for interoperability with a number of systems, for this reason, we have done this implementation.** \n\n## Usage\n\n### Sign\n\n```typescript\nSignedXml.Sign(algorithm: Algorithm, key: CryptoKey, data: Document, options?: OptionsSign): PromiseLike\u003cSignature\u003e;\n```\n\n__Parameters__\n\n| Name          | Description                                                             |\n|:--------------|:------------------------------------------------------------------------|\n| algorithm     | Signing [Algorithm](https://www.w3.org/TR/WebCryptoAPI/#algorithms)     |\n| key           | Signing [Key](https://www.w3.org/TR/WebCryptoAPI/#cryptokey-interface)  |\n| data          | XML document which must be signed                                       |\n| options       | Additional options                                                      |\n\n\n#### Options\n```typescript\ninterface OptionsSign {\n    /**\n     * Id of Signature\n     */\n    id?: string \n    /**\n     * Public key for KeyInfo block\n     */\n    keyValue?: CryptoKey;\n    /**\n     * List of X509 Certificates\n     */\n    x509?: string[];\n    /**\n     * List of Reference\n     * Default is Reference with hash alg SHA-256 and exc-c14n transform  \n     */\n    references?: OptionsSignReference[];\n}\n\ninterface OptionsSignReference {\n    /**\n     * Id of Reference\n     */\n    id?: string;\n    uri?: string;\n    /**\n     * Hash algorithm\n     */\n    hash: AlgorithmIdentifier;\n    /**\n     * List of transforms\n     */\n    transforms?: OptionsSignTransform[];\n}\n\ntype OptionsSignTransform = \"enveloped\" | \"c14n\" | \"exc-c14n\" | \"c14n-com\" | \"exc-c14n-com\" | \"base64\";\n```\n\n### Verify\n\n```typescript\nVerify(key?: CryptoKey): PromiseLike\u003cboolean\u003e;\n```\n\n__Parameters__\n\n| Name          | Description                                                             |\n|:--------------|:------------------------------------------------------------------------|\n| key           | Verifying [Key](https://www.w3.org/TR/WebCryptoAPI/#cryptokey-interface). Optional. If key not set it looks for keys in KeyInfo element of Signature.  |\n\n## EXAMPLES\n\nFor Sign/Verify operations you will need to use a Web Crypto CryptoKey. You can see [examples](https://github.com/diafygi/webcrypto-examples#rsassa-pkcs1-v1_5---generatekey) for an example of how to do that.\n\n### Initiating in NodeJs\n\n```javascript\n\"use strict\";\n\nconst WebCrypto = require(\"node-webcrypto-ossl\");\nconst crypto = new WebCrypto();\nconst XmlDSigJs = require(\"xmldsigjs\");\n\nXmlDSigJs.Application.setEngine(\"OpenSSL\", crypto);\n```\n\n### Initiating in Browser\n\nGet the latest version form [unpkg.com/xmldsigjs](https://unpkg.com/xmldsigjs)\n\n```html\n\u003cscript src=\"https://unpkg.com/xmldsigjs@\u003cversion\u003e/build/xmldsig.js\"\u003e\u003c/script\u003e\n```\n\n### Creating a XMLDSIG Signature\n\n```javascript\n\"use strict\";\n\nlet signature = new XmlDSigJs.SignedXml();\n\nsignature.Sign(                                  // Signing document\n    { name: \"RSASSA-PKCS1-v1_5\" },                        // algorithm \n    keys.privateKey,                                      // key \n    XmlDSigJs.Parse(xml),                                 // document\n    {                                                     // options\n        keyValue: keys.publicKey,\n        references: [\n            { hash: \"SHA-512\", transforms: [\"enveloped\", \"c14n\"] },\n        ]\n    })\n    .then(() =\u003e {\n        console.log(signature.toString());       // \u003cxml\u003e document with signature\n    })\n    .catch(e =\u003e console.log(e));\n```\n\n### Checking a XMLDSIG Signature \n\n\n```js\nlet doc = XmlDSigJs.Parse(xml);\nlet signature = doc.getElementsByTagNameNS(\"http://www.w3.org/2000/09/xmldsig#\", \"Signature\");\n\nlet signedXml = new XmlDSigJs.SignedXml(doc);\nsignedXml.LoadXml(signature[0]);\n\nsignedXml.Verify()\n    .then(res =\u003e {\n        console.log(\"Signature status:\", res);       // Signature status: true\n    })\n    .catch(e =\u003e console.log(e));\n```\n\n#### Browser Verify Example\n```HTML\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"/\u003e\n    \u003ctitle\u003eXMLDSIGjs Verify Sample\u003c/title\u003e\n\u003c/head\u003e\n\n\u003cbody\u003e\n    \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/7.7.0/polyfill.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://cdnjs.cloudflare.com/ajax/libs/asmCrypto/2.3.2/asmcrypto.all.es5.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://cdn.rawgit.com/indutny/elliptic/master/dist/elliptic.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/webcrypto-liner@1.1.2/build/webcrypto-liner.shim.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/xmldsigjs@2.0.27/build/xmldsig.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\"\u003e\n        fetch(\"signature.xml\")\n        .then(function(response) {\n            return response.text();\n        }).then(function(body) {\n            var xmlString = body;\n\n            var signedDocument = XmlDSigJs.Parse(xmlString);\n            var xmlSignature = signedDocument.getElementsByTagNameNS(\"http://www.w3.org/2000/09/xmldsig#\", \"Signature\");\n\n            var signedXml = new XmlDSigJs.SignedXml(signedDocument);\n            signedXml.LoadXml(xmlSignature[0]);\n            signedXml.Verify()\n            .then(function (res) {\n                console.log((res ? \"Valid\" : \"Invalid\") + \" signature\");\n            })\n            .catch(function (e) {\n                console.error(e);\n            });\n        })\n    \u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## TESTING\n\n### In NodeJS:\n\n```\nnpm test\n```\n\n### In the browser\nTo run the browser test you need to run a test server, from the test directory run: \n```\nnpm start\n```\n\nAnd the then browse to `http://localhost:3000'.\n\n## THANKS AND ACKNOWLEDGEMENT\nThis project takes inspiration (style, approach, design and code) from both the [Mono System.Security.Cryptography.Xml](https://github.com/mono/mono/tree/master/mcs/class/System.Security/System.Security.Cryptography.Xml) implementation as well as [xml-crypto](https://github.com/yaronn/xml-crypto).\n\n## RELATED\n- [Why XML Security is Broken](https://www.cs.auckland.ac.nz/~pgut001/pubs/xmlsec.txt)\n- [XML Signature Syntax and Processing](https://www.w3.org/TR/xmldsig-core/)\n- [XML Security Algorithm Cross-Reference](https://tools.ietf.org/html/rfc6931)\n- [XMLDSIG HTML Signing Profile](https://www.w3.org/2007/11/h6n/)\n- [Canonical XML](https://www.w3.org/TR/xml-c14n)\n- [Exclusive XML Canonicalization](https://www.w3.org/TR/xml-exc-c14n/)\n- [Internet X.509 Public Key Infrastructure Time-Stamp Protocol](https://www.ietf.org/rfc/rfc3161.txt)\n- [PKIjs](pkijs.org)\n- [@peculiar/webcrypto](https://github.com/PeculiarVentures/webcrypto)\n- [node-webcrypto-ossl](https://github.com/PeculiarVentures/node-webcrypto-ossl)\n- [node-webcrypto-p11](https://github.com/PeculiarVentures/node-webcrypto-p11)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeculiarventures%2Fxmldsigjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeculiarventures%2Fxmldsigjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeculiarventures%2Fxmldsigjs/lists"}