From 12cac31d4cb733cdc38ee49272aadd9585919873 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Sat, 13 Oct 2018 01:29:46 +0200
Subject: [PATCH 1/4] doc: document key pair generation encryption

---
 doc/api/crypto.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 2ba721d062296f..915f96722b37cd 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1923,6 +1923,14 @@ generateKeyPair('rsa', {
 On completion, `callback` will be called with `err` set to `undefined` and
 `publicKey` / `privateKey` representing the generated key pair.
 
+Private keys can be encrypted if the `type` is PKCS#8 or the `format` is PEM.
+If a `cipher` is specified and PKCS#8 was selected, an `EncryptedPrivateKeyInfo`
+structure will be produced. If PKCS#1 or SEC1 was selected and the `format` is
+PEM, RFC1421-style PEM-level encryption will be used. For maximum compatibility,
+it is recommended to use PKCS#8 for encrypted private keys. Since PKCS#8
+defines its own encryption mechanism, PEM-level encryption is not supported when
+encrypting a PKCS#8 key.
+
 If this method is invoked as its [`util.promisify()`][]ed version, it returns
 a `Promise` for an `Object` with `publicKey` and `privateKey` properties.
 
@@ -1984,6 +1992,14 @@ The return value `{ publicKey, privateKey }` represents the generated key pair.
 When PEM encoding was selected, the respective key will be a string, otherwise
 it will be a buffer containing the data encoded as DER.
 
+Private keys can be encrypted if the `type` is PKCS#8 or the `format` is PEM.
+If a `cipher` is specified and PKCS#8 was selected, an `EncryptedPrivateKeyInfo`
+structure will be produced. If PKCS#1 or SEC1 was selected and the `format` is
+PEM, RFC1421-style PEM-level encryption will be used. For maximum compatibility,
+it is recommended to use PKCS#8 for encrypted private keys. Since PKCS#8
+defines its own encryption mechanism, PEM-level encryption is not supported when
+encrypting a PKCS#8 key.
+
 ### crypto.getCiphers()
 <!-- YAML
 added: v0.9.3

From 11066fc2ea3f3d7c6c7091cf274b05a2249741e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@users.noreply.github.com>
Date: Mon, 19 Nov 2018 21:20:57 +0100
Subject: [PATCH 2/4] Use Sam's suggestion

---
 doc/api/crypto.md | 35 ++++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 915f96722b37cd..a09ef9fc49f375 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1923,13 +1923,15 @@ generateKeyPair('rsa', {
 On completion, `callback` will be called with `err` set to `undefined` and
 `publicKey` / `privateKey` representing the generated key pair.
 
-Private keys can be encrypted if the `type` is PKCS#8 or the `format` is PEM.
-If a `cipher` is specified and PKCS#8 was selected, an `EncryptedPrivateKeyInfo`
-structure will be produced. If PKCS#1 or SEC1 was selected and the `format` is
-PEM, RFC1421-style PEM-level encryption will be used. For maximum compatibility,
-it is recommended to use PKCS#8 for encrypted private keys. Since PKCS#8
-defines its own encryption mechanism, PEM-level encryption is not supported when
-encrypting a PKCS#8 key.
+PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
+the `cipher` and `format` options. The PKCS#8 `type` can be used with any
+`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
+`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
+when the PEM `format` is used. For maximum compatibility, it is recommended
+to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
+encryption mechanism, PEM-level encryption is not supported when encrypting
+a PKCS#8 key. See [RFC 5208] for PKCS#8 encryption and [RFC 1421][] for
+PKCS#1 and SEC1 encryption.
 
 If this method is invoked as its [`util.promisify()`][]ed version, it returns
 a `Promise` for an `Object` with `publicKey` and `privateKey` properties.
@@ -1991,14 +1993,15 @@ const { publicKey, privateKey } = generateKeyPairSync('rsa', {
 The return value `{ publicKey, privateKey }` represents the generated key pair.
 When PEM encoding was selected, the respective key will be a string, otherwise
 it will be a buffer containing the data encoded as DER.
-
-Private keys can be encrypted if the `type` is PKCS#8 or the `format` is PEM.
-If a `cipher` is specified and PKCS#8 was selected, an `EncryptedPrivateKeyInfo`
-structure will be produced. If PKCS#1 or SEC1 was selected and the `format` is
-PEM, RFC1421-style PEM-level encryption will be used. For maximum compatibility,
-it is recommended to use PKCS#8 for encrypted private keys. Since PKCS#8
-defines its own encryption mechanism, PEM-level encryption is not supported when
-encrypting a PKCS#8 key.
+PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
+the `cipher` and `format` options. The PKCS#8 `type` can be used with any
+`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
+`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
+when the PEM `format` is used. For maximum compatibility, it is recommended
+to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
+encryption mechanism, PEM-level encryption is not supported when encrypting
+a PKCS#8 key. See [RFC 5208] for PKCS#8 encryption and [RFC 1421][] for
+PKCS#1 and SEC1 encryption.
 
 ### crypto.getCiphers()
 <!-- YAML
@@ -3143,10 +3146,12 @@ the `crypto`, `tls`, and `https` modules and are generally specific to OpenSSL.
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [Nonce-Disrespecting Adversaries]: https://github.com/nonce-disrespect/nonce-disrespect
 [OpenSSL's SPKAC implementation]: https://www.openssl.org/docs/man1.1.0/apps/openssl-spkac.html
+[RFC 1421]: https://www.rfc-editor.org/rfc/rfc1421.txt
 [RFC 2412]: https://www.rfc-editor.org/rfc/rfc2412.txt
 [RFC 3526]: https://www.rfc-editor.org/rfc/rfc3526.txt
 [RFC 3610]: https://www.rfc-editor.org/rfc/rfc3610.txt
 [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
+[RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
 [encoding]: buffer.html#buffer_buffers_and_character_encodings
 [initialization vector]: https://en.wikipedia.org/wiki/Initialization_vector
 [scrypt]: https://en.wikipedia.org/wiki/Scrypt

From 464b674a45caede08c0024410b9cc9a66c491175 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
Date: Fri, 4 Jan 2019 15:27:57 +0100
Subject: [PATCH 3/4] Adapt to KeyObject API

---
 doc/api/crypto.md | 29 ++++++++++-------------------
 1 file changed, 10 insertions(+), 19 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index a09ef9fc49f375..85fa4ccf351042 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1157,6 +1157,16 @@ For private keys, the following encoding options can be used:
 When PEM encoding was selected, the result will be a string, otherwise it will
 be a buffer containing the data encoded as DER.
 
+PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
+the `cipher` and `format` options. The PKCS#8 `type` can be used with any
+`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
+`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
+when the PEM `format` is used. For maximum compatibility, it is recommended
+to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
+encryption mechanism, PEM-level encryption is not supported when encrypting
+a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for
+PKCS#1 and SEC1 encryption.
+
 ### keyObject.symmetricSize
 <!-- YAML
 added: v11.6.0
@@ -1923,16 +1933,6 @@ generateKeyPair('rsa', {
 On completion, `callback` will be called with `err` set to `undefined` and
 `publicKey` / `privateKey` representing the generated key pair.
 
-PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
-the `cipher` and `format` options. The PKCS#8 `type` can be used with any
-`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
-`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
-when the PEM `format` is used. For maximum compatibility, it is recommended
-to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
-encryption mechanism, PEM-level encryption is not supported when encrypting
-a PKCS#8 key. See [RFC 5208] for PKCS#8 encryption and [RFC 1421][] for
-PKCS#1 and SEC1 encryption.
-
 If this method is invoked as its [`util.promisify()`][]ed version, it returns
 a `Promise` for an `Object` with `publicKey` and `privateKey` properties.
 
@@ -1993,15 +1993,6 @@ const { publicKey, privateKey } = generateKeyPairSync('rsa', {
 The return value `{ publicKey, privateKey }` represents the generated key pair.
 When PEM encoding was selected, the respective key will be a string, otherwise
 it will be a buffer containing the data encoded as DER.
-PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
-the `cipher` and `format` options. The PKCS#8 `type` can be used with any
-`format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
-`cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
-when the PEM `format` is used. For maximum compatibility, it is recommended
-to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
-encryption mechanism, PEM-level encryption is not supported when encrypting
-a PKCS#8 key. See [RFC 5208] for PKCS#8 encryption and [RFC 1421][] for
-PKCS#1 and SEC1 encryption.
 
 ### crypto.getCiphers()
 <!-- YAML

From fcfa241da7e4991ae6ef0b4bb4c33b1f76e86dd2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@users.noreply.github.com>
Date: Fri, 4 Jan 2019 19:29:41 +0100
Subject: [PATCH 4/4] Use Trott's suggestion

---
 doc/api/crypto.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 85fa4ccf351042..bc842062d06257 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -1161,8 +1161,8 @@ PKCS#1, SEC1, and PKCS#8 type keys can be encrypted by using a combination of
 the `cipher` and `format` options. The PKCS#8 `type` can be used with any
 `format` to encrypt any key algorithm (RSA, EC, or DH) by specifying a
 `cipher`. PKCS#1 and SEC1 can only be encrypted by specifying a `cipher`
-when the PEM `format` is used. For maximum compatibility, it is recommended
-to use PKCS#8 for encrypted private keys. Since PKCS#8 defines its own
+when the PEM `format` is used. For maximum compatibility, use PKCS#8 for
+encrypted private keys. Since PKCS#8 defines its own
 encryption mechanism, PEM-level encryption is not supported when encrypting
 a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for
 PKCS#1 and SEC1 encryption.