Skip to content

Openssl servername documentation improvement

Filip Aleksic requested to merge docs-openssl-improvements into master

What does this MR do?

  • Included information about -servername variable on several pages to specify the domain we are trying to reach via openssl
  • Changed openssl to use the embedded binary - /opt/gitlab/embedded/bin/openssl

The reason for the change behind -servername is simple, if not defined we are expecting the webserver to return the default one. By specifying the -servername we are specifying the domain for the SSL certificate.

Here's an example:

$ echo | openssl s_client -connect gitlab.com:443 -servername gitlab.com | head
depth=2 C = IE, O = Baltimore, OU = CyberTrust, CN = Baltimore CyberTrust Root
verify return:1
depth=1 C = US, O = "Cloudflare, Inc.", CN = Cloudflare Inc ECC CA-3
verify return:1
depth=0 C = US, ST = California, L = San Francisco, O = "Cloudflare, Inc.", CN = gitlab.com
verify return:1
DONE
CONNECTED(00000005)
---
Certificate chain
 0 s:/C=US/ST=California/L=San Francisco/O=Cloudflare, Inc./CN=gitlab.com
   i:/C=US/O=Cloudflare, Inc./CN=Cloudflare Inc ECC CA-3
 1 s:/C=US/O=Cloudflare, Inc./CN=Cloudflare Inc ECC CA-3
   i:/C=IE/O=Baltimore/OU=CyberTrust/CN=Baltimore CyberTrust Root
---
Server certificate
-----BEGIN CERTIFICATE-----

In the above example we can see the proper SSL certificate being returned. When the -servername not specified:

$ echo | openssl s_client -connect gitlab.com:443 | head
4348249644:error:14004410:SSL routines:CONNECT_CR_SRVR_HELLO:sslv3 alert handshake failure:/AppleInternal/Library/BuildRoots/a0876c02-1788-11ed-b9c4-96898e02b808/Library/Caches/com.apple.xbs/Sources/libressl/libressl-2.8/ssl/ssl_pkt.c:1200:SSL alert number 40
4348249644:error:140040E5:SSL routines:CONNECT_CR_SRVR_HELLO:ssl handshake failure:/AppleInternal/Library/BuildRoots/a0876c02-1788-11ed-b9c4-96898e02b808/Library/Caches/com.apple.xbs/Sources/libressl/libressl-2.8/ssl/ssl_pkt.c:585:
CONNECTED(00000005)
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 7 bytes and written 0 bytes
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported

We end up relying on the server on the other end to provide us with what it thinks is the certificate, and depending on the configuration, sometimes the default SSL certificate isn't returned. By explicitly using -servername we reduce the chance of an error.

Related issues

None

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
Edited by Filip Aleksic

Merge request reports