You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+107-13
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,45 @@ Install with [npm](http://github.com/isaacs/npm):
10
10
11
11
A pre requisite it to have [openssl](http://www.openssl.org/) installed and its /bin to be on the system path. I used version 1.0.1c but it should work on older versions too.
12
12
13
+
## Supported Algorithms
14
+
15
+
### Canonicalization and Transformation Algorithms
[You are able to extend xml-crypto with custom algorithms.](#customizing-algorithms)
41
+
42
+
13
43
## Signing Xml documents
44
+
45
+
When signing a xml document you can specify the following properties on a `SignedXml` instance to customize the signature process:
46
+
47
+
-`sign.signingKey` - **[required]** a `Buffer` or pem encoded `String` containing your private key
48
+
-`sign.keyInfoProvider` - **[optional]** a key info provider instance, see [customizing algorithms](#customizing-algorithms) for an implementation example
49
+
-`sign.signatureAlgorithm` - **[optional]** one of the supported [signature algorithms](#signature-algorithms). Ex: `sign.signatureAlgorithm = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"`
50
+
-`sign.canonicalizationAlgorithm` - **[optional]** one of the supported [canonicalization algorithms](#canonicalization-and-transformation-algorithms). Ex: `sign.canonicalizationAlgorithm = "http://www.w3.org/2001/10/xml-exc-c14n#WithComments"`
51
+
14
52
Use this code:
15
53
16
54
`````javascript
@@ -56,18 +94,21 @@ The result will be:
56
94
</library>
57
95
`````
58
96
97
+
Note:
59
98
60
-
Notes:
61
-
62
-
sig.getSignedXml() returns the original xml document with the signature pushed as the last child of the root node (as above). This assumes you are not signing the root node but only sub node(s) otherwise this is not valid. If you do sign the root node call sig.getSignatureXml() to get just the signature part and sig.getOriginalXmlWithIds() to get the original xml with Id attributes added on relevant elements (required for validation).
99
+
To generate a `<X509Data></X509Data>` element in the signature you must provide a key info implementation, see [customizing algorithms](#customizing-algorithms) for an example.
63
100
64
101
## Verifying Xml documents
65
102
103
+
When verifying a xml document you must specify the following properties on a ``SignedXml` instance:
104
+
105
+
-`sign.keyInfoProvider` - **[required]** a key info provider instance containing your certificate, see [customizing algorithms](#customizing-algorithms) for an implementation example
106
+
66
107
You can use any dom parser you want in your code (or none, depending on your usage). This sample uses [xmldom](https://github.com/jindw/xmldom) so you should install it first:
67
108
68
-
npm install xmldom
109
+
npm install xmldom
69
110
70
-
Then run:
111
+
Example:
71
112
72
113
`````javascript
73
114
var select =require('xml-crypto').xpath
@@ -87,18 +128,61 @@ Then run:
87
128
if (!res) console.log(sig.validationErrors)
88
129
`````
89
130
131
+
if the verification process fails `sig.validationErrors` will have the errors.
132
+
90
133
Note:
91
134
92
135
The xml-crypto api requires you to supply it separately the xml signature ("<Signature>...</Signature>", in loadSignature) and the signed xml (in checkSignature). The signed xml may or may not contain the signature in it, but you are still required to supply the signature separately.
93
136
94
-
## Supported Algorithms
95
-
The first release always uses the following algorithems:
See [xpath.js](https://github.com/yaronn/xpath.js) for usage
143
+
144
+
### SignedXml
145
+
146
+
The `SignedXml` constructor provides an abstraction for sign and verify xml documents. The object is constructed using `new SignedXml([idMode])` where:
147
+
148
+
-`idMode` - if the value of `"wssecurity"` is passed it will create/validate id's with the ws-security namespace.
149
+
150
+
*API*
151
+
152
+
A `SignedXml` object provides the following methods:
153
+
154
+
To sign xml documents:
155
+
156
+
-`addReference(xpath, [transforms], [digestAlgorithm])` - adds a reference to a xml element where:
157
+
-`xpath` - a string containing a XPath expression referencing a xml element
158
+
-`transforms` - an array of [transform algorithms](#canonicalization-and-transformation-algorithms), the referenced element will be transformed for each value in the array
159
+
-`digestAlgorithm` - one of the supported [hashing algorithms](#hashing algorithms)
160
+
-`computeSignature(xml, [options])` - compute the signature of the given xml where:
161
+
-`xml` - a string containing a xml document
162
+
-`options` - an object with the following properties:
163
+
-`prefix` - adds this value as a prefix for the generated signature tags
164
+
-`attrs` - a hash of attributes and values `attrName: value` to add to the signature root node
165
+
-`location` - customize the location of the signature, pass an object with a `reference` key which should contain a XPath expression to a reference node, an `action` key which should contain one of the following values: `append`, `prepend`, `before`, `after`
166
+
-`getSignedXml()` - returns the original xml document with the signature in it, **must be called only after `computeSignature`**
167
+
-`getSignatureXml()` - returns just the signature part, **must be called only after `computeSignature`**
168
+
-`getOriginalXmlWithIds()` - returns the original xml with Id attributes added on relevant elements (required for validation), **must be called only after `computeSignature`**
169
+
170
+
To verify xml documents:
171
+
172
+
-`loadSignature(signatureXml)` - loads the signature where:
173
+
-`signatureXml` - a string or node object (like an [xml-dom](https://github.com/jindw/xmldom) node) containing the xml representation of the signature
174
+
-`checkSignature(xml)` - validates the given xml document and returns true if the validation was successful, `sig.validationErrors` will have the validation errors if any, where:
175
+
-`xml` - a string containing a xml document
176
+
177
+
178
+
### FileKeyInfo
179
+
180
+
A basic key info provider implementation using `fs.readFileSync(file)`, is constructed using `new FileKeyInfo([file])` where:
181
+
182
+
-`file` - a path to a pem encoded certificate
183
+
184
+
See [verifying xml documents](#verifying-xml-documents) for an example usage
100
185
101
-
you are able to extend xml-crypto with further algorithms.
102
186
103
187
## Customizing Algorithms
104
188
The following sample shows how to sign a message using custom algorithms.
@@ -118,8 +202,10 @@ Implement it if you want to create a signature with a KeyInfo section, or you wa
//you can use the keyInfo parameter to extract the key in any way you want
@@ -259,6 +345,14 @@ If you have .pfx certificates you can convert them to .pem using [openssl](http:
259
345
260
346
Then you could use the result as is for the purpose of signing. For the purpose of validation open the resulting .pem with a text editor and copy from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- (including) to a new text file and save it as .pem.
261
347
348
+
## Examples
349
+
350
+
-[how to sign a root node](#)*coming soon*
351
+
-[how to add a prefix for the signature]*coming soon*
352
+
-[how to specify the location of the signature](#)*coming soon*
353
+
354
+
*more examples coming soon*
355
+
262
356
## Development
263
357
The test framework is [nodeunit](https://github.com/caolan/nodeunit). To run tests use:
0 commit comments