crypto: add sign/verify support for RSASSA-PSS · nodejs/node@a7d4cad
@@ -898,17 +898,32 @@ console.log(sign.sign(privateKey).toString('hex'));
898898### sign.sign(private_key[, output_format])
899899<!-- YAML
900900added: v0.1.92
901+changes:
902+ - version: REPLACEME
903+ pr-url: https://github.com/nodejs/node/pull/11705
904+ description: Support for RSASSA-PSS and additional options was added.
901905-->
902906903907Calculates the signature on all the data passed through using either
904908[`sign.update()`][] or [`sign.write()`][stream-writable-write].
905909906910The `private_key` argument can be an object or a string. If `private_key` is a
907911string, it is treated as a raw key with no passphrase. If `private_key` is an
908-object, it is interpreted as a hash containing two properties:
912+object, it must contain one or more of the following properties:
909913910-* `key`: {string} - PEM encoded private key
914+* `key`: {string} - PEM encoded private key (required)
911915* `passphrase`: {string} - passphrase for the private key
916+* `padding`: {integer} - Optional padding value for RSA, one of the following:
917+* `crypto.constants.RSA_PKCS1_PADDING` (default)
918+* `crypto.constants.RSA_PKCS1_PSS_PADDING`
919+920+ Note that `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
921+ used to sign the message as specified in section 3.1 of [RFC 4055][].
922+* `saltLength`: {integer} - salt length for when padding is
923+`RSA_PKCS1_PSS_PADDING`. The special value
924+`crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
925+ size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the
926+ maximum permissible value.
912927913928The `output_format` can specify one of `'latin1'`, `'hex'` or `'base64'`. If
914929`output_format` is provided a string is returned; otherwise a [`Buffer`][] is
@@ -991,11 +1006,33 @@ This can be called many times with new data as it is streamed.
9911006### verifier.verify(object, signature[, signature_format])
9921007<!-- YAML
9931008added: v0.1.92
1009+changes:
1010+ - version: REPLACEME
1011+ pr-url: https://github.com/nodejs/node/pull/11705
1012+ description: Support for RSASSA-PSS and additional options was added.
9941013-->
1014+- `object` {string | Object}
1015+- `signature` {string | Buffer | Uint8Array}
1016+- `signature_format` {string}
99510179961018Verifies the provided data using the given `object` and `signature`.
997-The `object` argument is a string containing a PEM encoded object, which can be
998-one an RSA public key, a DSA public key, or an X.509 certificate.
1019+The `object` argument can be either a string containing a PEM encoded object,
1020+which can be an RSA public key, a DSA public key, or an X.509 certificate,
1021+or an object with one or more of the following properties:
1022+1023+* `key`: {string} - PEM encoded public key (required)
1024+* `padding`: {integer} - Optional padding value for RSA, one of the following:
1025+* `crypto.constants.RSA_PKCS1_PADDING` (default)
1026+* `crypto.constants.RSA_PKCS1_PSS_PADDING`
1027+1028+ Note that `RSA_PKCS1_PSS_PADDING` will use MGF1 with the same hash function
1029+ used to verify the message as specified in section 3.1 of [RFC 4055][].
1030+* `saltLength`: {integer} - salt length for when padding is
1031+`RSA_PKCS1_PSS_PADDING`. The special value
1032+`crypto.constants.RSA_PSS_SALTLEN_DIGEST` sets the salt length to the digest
1033+ size, `crypto.constants.RSA_PSS_SALTLEN_AUTO` (default) causes it to be
1034+ determined automatically.
1035+9991036The `signature` argument is the previously calculated signature for the data, in
10001037the `signature_format` which can be `'latin1'`, `'hex'` or `'base64'`.
10011038If a `signature_format` is specified, the `signature` is expected to be a
@@ -1902,6 +1939,21 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
19021939<td><code>RSA_PKCS1_PSS_PADDING</code></td>
19031940<td></td>
19041941</tr>
1942+<tr>
1943+<td><code>RSA_PSS_SALTLEN_DIGEST</code></td>
1944+<td>Sets the salt length for `RSA_PKCS1_PSS_PADDING` to the digest size
1945+ when signing or verifying.</td>
1946+</tr>
1947+<tr>
1948+<td><code>RSA_PSS_SALTLEN_MAX_SIGN</code></td>
1949+<td>Sets the salt length for `RSA_PKCS1_PSS_PADDING` to the maximum
1950+ permissible value when signing data.</td>
1951+</tr>
1952+<tr>
1953+<td><code>RSA_PSS_SALTLEN_AUTO</code></td>
1954+<td>Causes the salt length for `RSA_PKCS1_PSS_PADDING` to be determined
1955+ automatically when verifying a signature.</td>
1956+</tr>
19051957<tr>
19061958<td><code>POINT_CONVERSION_COMPRESSED</code></td>
19071959<td></td>
@@ -1977,6 +2029,7 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
19772029[publicly trusted list of CAs]: https://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
19782030[RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
19792031[RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
2032+[RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
19802033[stream]: stream.html
19812034[stream-writable-write]: stream.html#stream_writable_write_chunk_encoding_callback
19822035[Crypto Constants]: #crypto_crypto_constants_1