Discourage use of cert subject common name, examples and docs

publishlab · May 22, 2024 · 12f8096 · 12f8096
1 parent fd0d13e
commit 12f8096
Show file tree

Hide file tree

Showing 11 changed files with 19 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -113,8 +113,7 @@ const privateRsaKey = await acme.crypto.createPrivateRsaKey();
 const privateEcdsaKey = await acme.crypto.createPrivateEcdsaKey();
 
 const [certificateKey, certificateCsr] = await acme.crypto.createCsr({
-    commonName: '*.example.com',
-    altNames: ['example.com'],
+    altNames: ['example.com', '*.example.com'],
 });
 ```
 

diff --git a/examples/api.js b/examples/api.js
@@ -135,8 +135,7 @@ module.exports = async () => {
 
     /* Finalize order */
     const [key, csr] = await acme.crypto.createCsr({
-        commonName: '*.example.com',
-        altNames: ['example.com'],
+        altNames: ['example.com', '*.example.com'],
     });
 
     const finalized = await client.finalizeOrder(order, csr);

diff --git a/examples/auto.js b/examples/auto.js
@@ -95,7 +95,7 @@ module.exports = async () => {
 
     /* Create CSR */
     const [key, csr] = await acme.crypto.createCsr({
-        commonName: 'example.com',
+        altNames: ['example.com'],
     });
 
     /* Certificate */

diff --git a/examples/dns-01/dns-01.js b/examples/dns-01/dns-01.js
@@ -41,8 +41,7 @@ function log(m) {
 
         log(`Creating CSR for ${WILDCARD_DOMAIN}`);
         const [key, csr] = await acme.crypto.createCsr({
-            commonName: WILDCARD_DOMAIN,
-            altNames: [`*.${WILDCARD_DOMAIN}`],
+            altNames: [WILDCARD_DOMAIN, `*.${WILDCARD_DOMAIN}`],
         });
 
         log(`Ordering certificate for ${WILDCARD_DOMAIN}`);

diff --git a/examples/http-01/http-01.js b/examples/http-01/http-01.js
@@ -51,7 +51,7 @@ async function getCertOnDemand(client, servername, attempt = 0) {
     /* Create CSR */
     log(`Creating CSR for ${servername}`);
     const [key, csr] = await acme.crypto.createCsr({
-        commonName: servername,
+        altNames: [servername],
     });
 
     /* Order certificate */

diff --git a/examples/tls-alpn-01/tls-alpn-01.js b/examples/tls-alpn-01/tls-alpn-01.js
@@ -50,7 +50,7 @@ async function getCertOnDemand(client, servername, attempt = 0) {
     /* Create CSR */
     log(`Creating CSR for ${servername}`);
     const [key, csr] = await acme.crypto.createCsr({
-        commonName: servername,
+        altNames: [servername],
     });
 
     /* Order certificate */

diff --git a/src/client.js b/src/client.js
@@ -666,7 +666,7 @@ class AcmeClient {
      * @example Order a certificate using auto mode
      * ```js
      * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
-     *     commonName: 'test.example.com',
+     *     altNames: ['test.example.com'],
      * });
      *
      * const certificate = await client.auto({
@@ -685,7 +685,7 @@ class AcmeClient {
      * @example Order a certificate using auto mode with preferred chain
      * ```js
      * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
-     *     commonName: 'test.example.com',
+     *     altNames: ['test.example.com'],
      * });
      *
      * const certificate = await client.auto({

diff --git a/src/crypto/forge.js b/src/crypto/forge.js
@@ -342,11 +342,12 @@ function formatCsrAltNames(altNames) {
  * @example Create a Certificate Signing Request
  * ```js
  * const [certificateKey, certificateRequest] = await acme.forge.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  * });
  * ```
  *
  * @example Certificate Signing Request with both common and alternative names
+ * > *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
  * ```js
  * const [certificateKey, certificateRequest] = await acme.forge.createCsr({
  *     keySize: 4096,
@@ -358,7 +359,7 @@ function formatCsrAltNames(altNames) {
  * @example Certificate Signing Request with additional information
  * ```js
  * const [certificateKey, certificateRequest] = await acme.forge.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  *     country: 'US',
  *     state: 'California',
  *     locality: 'Los Angeles',
@@ -373,7 +374,7 @@ function formatCsrAltNames(altNames) {
  * const certificateKey = await acme.forge.createPrivateKey();
  *
  * const [, certificateRequest] = await acme.forge.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  * }, certificateKey);
  */
 

diff --git a/src/crypto/index.js b/src/crypto/index.js
@@ -413,11 +413,12 @@ function createSubjectAltNameExtension(altNames) {
  * @example Create a Certificate Signing Request
  * ```js
  * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  * });
  * ```
  *
  * @example Certificate Signing Request with both common and alternative names
+ * > *Warning*: Certificate subject common name has been [deprecated](https://letsencrypt.org/docs/glossary/#def-CN) and its use is [discouraged](https://cabforum.org/uploads/BRv1.2.3.pdf).
  * ```js
  * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
  *     keySize: 4096,
@@ -429,7 +430,7 @@ function createSubjectAltNameExtension(altNames) {
  * @example Certificate Signing Request with additional information
  * ```js
  * const [certificateKey, certificateRequest] = await acme.crypto.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  *     country: 'US',
  *     state: 'California',
  *     locality: 'Los Angeles',
@@ -444,7 +445,7 @@ function createSubjectAltNameExtension(altNames) {
  * const certificateKey = await acme.crypto.createPrivateEcdsaKey();
  *
  * const [, certificateRequest] = await acme.crypto.createCsr({
- *     commonName: 'test.example.com',
+ *     altNames: ['test.example.com'],
  * }, certificateKey);
  */
 

diff --git a/test/50-client.spec.js b/test/50-client.spec.js
@@ -110,8 +110,8 @@ describe('client', () => {
 
             it('should generate certificate signing request', async () => {
                 [, testCsr] = await acme.crypto.createCsr({ commonName: testDomain }, await createKeyFn());
-                [, testCsrAlpn] = await acme.crypto.createCsr({ commonName: testDomainAlpn }, await createKeyFn());
-                [, testCsrWildcard] = await acme.crypto.createCsr({ commonName: testDomainWildcard }, await createKeyFn());
+                [, testCsrAlpn] = await acme.crypto.createCsr({ altNames: [testDomainAlpn] }, await createKeyFn());
+                [, testCsrWildcard] = await acme.crypto.createCsr({ altNames: [testDomainWildcard] }, await createKeyFn());
             });
 
             it('should resolve certificate issuers [ACME_CAP_ALTERNATE_CERT_ROOTS]', async function () {

diff --git a/test/70-auto.spec.js b/test/70-auto.spec.js
@@ -307,8 +307,7 @@ describe('client.auto', () => {
 
             it('should order wildcard certificate', async () => {
                 const [, csr] = await acme.crypto.createCsr({
-                    commonName: testWildcardDomain,
-                    altNames: [`*.${testWildcardDomain}`],
+                    altNames: [testWildcardDomain, `*.${testWildcardDomain}`],
                 }, await createKeyFn());
 
                 const cert = await testClient.auto({