chore: add documentation regarding TLS certs without SANs (#1113)

johnstcn · mafredri · web-flow · commit 27f6514c8ffd · 2022-09-05T17:13:18.000+01:00
This commit documents the requirement for SANs in TLS certificates.

Co-authored-by: Mathias Fredriksson &lt;mafredri@gmail.com&gt;
diff --git a/images/tls-certificates.md b/images/tls-certificates.md
@@ -15,6 +15,9 @@ following reasons:
 - The image doesn't come with any ca-certificates
 - You're using an internal certificate authority
 
+Coder workspaces may also fail to build if the TLS certificate used by Coder is
+not present in the image, or if there is some issue with the certificate.
+
 ## Adding certificates for Coder
 
 To add certificates to your image and have them recognized by Coder:
@@ -38,3 +41,53 @@ within the workspace will use the certificates when making requests.
 The specific process to add system-level certificates depends on the Linux
 distribution that you're using, but it is typically done by adding your
 certificates to your system's trusted CA repository.
+
+## TLS Certificate Requirements
+
+Since the publication of RFC 2818 in 2000, the `commonName` field has been
+[considered deprecated](https://groups.google.com/a/chromium.org/g/security-dev/c/IGT2fLJrAeo/m/csf_1Rh1AwAJ).
+
+The Go programming language, which Coder uses, recently began enforcing this and
+ignoring the `commonName` field (source) in favor of the Subject Alternative
+Name (SAN) field.
+
+This essentially means that SSL certificates are required to use
+`Subject Alternative Name` instead of `commonName`. If you attempt to use a
+certificate having `commonName` with Coder, you may see the following error:
+
+```shell
+x509: certificate relies on legacy Common Name field, use SANs instead
+```
+
+Certificates may specify both fields for interoperability with existing software
+that requires the `commonName` field.
+
+If you see this error when building a workspace or performing other operations
+with Coder workspaces, you may be running into the aforementioned issue. To verify
+that this is the case, you can inspect the certificate of your Coder deployment
+with the following command:
+
+```shell
+openssl s_client -connect coder.domain.tld:443 < /dev/null 2>/dev/null \|
+sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' \|
+openssl x509 -text -noout \|
+grep -A1 'Subject Alternative Name'
+```
+
+If your certificate has SANs specified, the expected output for the above command
+would be similar to the following:
+
+```shell
+           X509v3 Subject Alternative Name:
+                DNS:*.coder.domain.tld, DNS:coder.domain.tld, DNS:domain.tld
+```
+
+Otherwise, a blank output is expected.
+
+To fix the issue, a new TLS certificate is required that does not rely solely on
+the `commmonName` field. In the above example, this would equate to adding the
+following arguments to the `openssl` invocation to generate the certificate:
+
+```shell
+-addext "subjectAltName = DNS:domain-name.com"
+```
diff --git a/manifest.json b/manifest.json
@@ -191,7 +191,7 @@
             },
             {
               "path": "./setup/air-gapped/offline-docs.md"
-            }            
+            }
           ]
         },
         {

Original file line number	Diff line number	Diff line change
`@@ -191,7 +191,7 @@`
`191`	`191`	`},`
`192`	`192`	`{`
`193`	`193`	`"path": "./setup/air-gapped/offline-docs.md"`
`194`		`- }`
	`194`	`+ }`
`195`	`195`	`]`
`196`	`196`	`},`
`197`	`197`	`{`