Skip to content

Commit b9b2ba2

Browse files
tniessenaddaleax
authored andcommitted
doc: document key encryption options
PR-URL: #23632 Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
1 parent 465d02b commit b9b2ba2

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

doc/api/crypto.md

+12
Original file line numberDiff line numberDiff line change
@@ -1157,6 +1157,16 @@ For private keys, the following encoding options can be used:
11571157
When PEM encoding was selected, the result will be a string, otherwise it will
11581158
be a buffer containing the data encoded as DER.
11591159

1160+
PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
1161+
the `cipher` and `format` options. The PKCS#8 `type` can be used with any
1162+
`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
1163+
`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
1164+
when the PEM `format` is used. For maximum compatibility, use PKCS#8 for
1165+
encrypted private keys. Since PKCS#8 defines its own
1166+
encryption mechanism, PEM-level encryption is not supported when encrypting
1167+
a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for
1168+
PKCS#1 and SEC1 encryption.
1169+
11601170
### keyObject.symmetricSize
11611171
<!-- YAML
11621172
added: v11.6.0
@@ -3127,10 +3137,12 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
31273137
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
31283138
[Nonce-Disrespecting Adversaries]: https://github.com/nonce-disrespect/nonce-disrespect
31293139
[OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/man1.1.0/apps/openssl-spkac.html
3140+
[RFC 1421]: https://www.rfc-editor.org/rfc/rfc1421.txt
31303141
[RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
31313142
[RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
31323143
[RFC 3610]: https://www.rfc-editor.org/rfc/rfc3610.txt
31333144
[RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
3145+
[RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
31343146
[encoding]: buffer.html#buffer_buffers_and_character_encodings
31353147
[initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector
31363148
[scrypt]: https://en.wikipedia.org/wiki/Scrypt

0 commit comments

Comments
 (0)