Web certificate and DNS requirements

Deephaven uses a web server certificate to set up secure communications and trust with client systems.

When you make a secured connection to a Web service, two components work fairly closely together: name resolution and the service's certificate.

  • Name resolution is the lookup process by which a client can find a server to connect to based on a URL like https://deephaven-1.mydomain.com:8000/iriside.
  • The service's certificate comes into play once the connection is made, and proves to the client that the machine it connected to is really deephaven-1.mydomain.com.

Name resolution

The Internet standard used for name resolution is DNS (Domain Name System). Typically, DNS is managed separately for each domain or sub-domain. So, for mydomain.com, there is a database - a DNS server - with names and addresses of different machines in this domain, and a client trying to connect to deephaven-1.mydomain.com will request the address information from this DNS server.

If you are setting up new machines or new Kubernetes service endpoints for Deephaven, the names by which you will connect to these services must be registered in a DNS database. Depending on your organization, this may be something you can do yourself, something automated in your infrastructure pipeline, or something you must request from a network administration team.

Web certificates

Web certificates are created (issued) by a set of central servers configured as trusted certificate authorities (CAs). There are two sources of certificates: private CAs and public CAs.

Many large organizations have an internal set of private CAs. To use these CAs, all the user systems have to trust them. This is typically configured automatically when new systems are built or joined to the network. Such private certificate infrastructures often have an Intranet page where users can submit certificate requests. Depending on organizational policies, you may be able to directly request and obtain web server certificates instantly, or you may be able to submit a request and get your certificate after an approval process.

Tip

If you click on the left end of the address in your browser when connected to an internal site on your network, you can view certificate information, including the issuer of the certificate. If the issuer is in your organization's domain, then you have a private certificate authority in your organization, and that is where you will probably need to get certificates for your Deephaven installation.

Public CAs are companies that have established themselves as well-known and trustworthy authorities so that trust of their certificate issuers is built-in to browsers and other software. Verisign, LetsEncrypt, and GoDaddy, are three popular public CAs. Some public CAs are free, while others may charge a fee to issue a Web server certificate. Identity verification for the person and organization requesting the certificate may be required.

Deephaven requirements

  • DNS record(s) are needed
    • All machines used for Deephaven will need DNS entries.
    • DNS entries are required for all of these interfaces if servers have multiple, differently-named interfaces over which Deephaven-related connections will be made.
    • Additional alias records can be added in DNS (either A records or CNAMEs) to allow use of friendly names when accessing Deephaven.
  • An x509 Web server certificate is required
    • The certificate's SAN (Subject Alternative Name block), must contain the names of *all Deephaven servers and aliases, or a wildcard that matches the domain being used.
    • Names must be in the same form as used by clients and server to server connections. Typically these will be fully-qualified domain names, such as deephaven-1.mydomain.com, but short names, such as deephaven-1 and aliases, can also be added.
    • It must have a separate key file that does not have a password.
    • The certificate must also allow:
      • Extended Key Usage *TLS Web Server Authentication
    • If you are using a private certificate authority, the certificate for the issuer system must also be included in the certificate file.

*If Envoy is used, only the names used by client URLs for the initial connection need to be in the SAN block. (Deephaven deployments on Kubernetes always use Envoy. Envoy is optional for other deployments.)

Warning

Some certificate-issuing processes default to adding a CN (Common Name) for the requested certificate but do not add a SAN block. This is no longer a compliant practice, and it will not work for a Deephaven installation.

Tip

On Linux and MacOS systems, a web certificate file can be examined with the openssl utility:

openssl x509 -in <certificate file> -noout -text

This will show the certificate's contents, including its dates of validity, which server issued it, and the contents of the Subject Alternative Name block.

Use of friendly names

DNS allows multiple entries for single endpoints. Two options for this are: additional A records and CNAMEs.

  • An A record maps a name to an IP address. DNS allows more than one A record per IP address. So, you might have a server named at683rr5.mydomain.com at 10.1.0.15, and you have an A record for that, but then you set up a second A record mapping deephaven-prod.mydomain.com to 10.1.0.15.
  • A CNAME maps a name to another name. Typically, a CNAME maps to an A record name, but it could also map to another CNAME. The advantage of CNAMEs is that if the IP address changes, the CNAMEs don't need to be updated, but all A records will have to be updated. With CNAMEs, you might have a server named at683rr5.mydomain.com at 10.1.0.15, and you have an A record for that, but then you set up a CNAME mapping deephaven-prod.mydomain.com to at683rr5.mydomain.com.

With either of the above options, both at683rr5.mydomain.com and deephaven-prod.mydomain.com will reach the server at 10.1.0.15.

Important

Any names used to access Deephaven on a server must be in the SAN block of the certificate, regardless of how those names were added. All A records and all CNAME DNS names used to access Deephaven services must be in the SAN block of the certificate.