ps-config-domains.adoc

= Configuring Domains and Certificates (TLS Context) for a Private Space

CloudHub 2.0 uses Transport Layer Security (TLS) contexts to encrypt
inbound traffic to the private space.

TLS contexts enable your apps to be reached at custom domains and, optionally, enable partial client authentication.

Each private space includes one TLS context by default (for traffic to `cloudhub.io`), which can't be removed.
The default certificate renews automatically and requires no action from the user.
You can create additional TLS contexts as required.

The TLS contexts that you configure for the private space define the domains that are available
when deploying apps to the private spaces.
See xref:ch2-config-endpoints-paths.adoc[].

== TLS Contexts

Each TLS context includes a keystore and an optional truststore.

To <<create-tls-context,create a TLS context>>:

. Upload the keystore.
. Upload the truststore (optional).
. Accept the default ciphers or select ciphers to add or remove.


=== Keystore

A _keystore_ is a repository of security certificates (either authorization certificates or public key certificates), along with their corresponding private keys used, for example, in SSL encryption.

The keystore allows communication to your app using custom domains.

CloudHub 2.0 supports the following keystore types:

PEM (Privacy-Enhanced Mail)::
+
A PEM file is a Base64-encoded ASCII file with a `.cer`, `.crt`, or `.pem` extension.
+
For PEM, the keystore consists of:
+
--
*** Public certificate
*** Private key
*** Certificate Authority (CA) path file (optional)

The keystore in PEM format uses TLS default values.
--
JKS (Java Keystore)::
+
A JKS file is a repository for authorization or public key certificates and does not store secret keys.
+
Use this option to upload a JKS file and use TLS default values.
With this option, you can't change the default values for TLS versions, ciphers, and other TLS configuration options.

=== Truststore

A truststore is a set of client certificates that the server checks against to enforce partial client authentication.
The optional truststore identifies trusted external clients or certificate authorities (CAs).

To enable partial client authentication, configure a truststore.
If a truststore is not configured, partial client authentication is disabled.

CloudHub 2.0 accepts truststore files in PEM formats.

=== DNS Targets

Configure a DNS target to allow clients to reach your applications from within or outside of the private network.

_Public DNS targets_ allow external clients to reach your applications at custom domains.
_Private DNS targets_ can only be reached from inside a private network, or through VPN or transit gateway connections. Use them with internal DNS or allowlists in your connected external networks, so clients in those networks may make requests to your applications.

=== Ciphers

When you add the TLS context, you can select the ciphers to use with the TLS context.


[[before-you-begin]]
== Before You Begin

. Generate a keystore:
+
** xref:ps-config-ssl-endpoints.adoc#pem[PEM]
** xref:mule-runtime::tls-configuration.adoc#generate-a-keystore[JKS]
. Generate a xref:mule-runtime::tls-configuration.adoc#truststore-generation[truststore] (if you want to enable partial client authentication).
. Create DNS records for your domains.
+
To enable traffic to reach the apps deployed to the private space using a custom domain:
+
.. Log in to your domain registrar.
+
Use https://www.whois.com/[Whois^] to look up your registrar.
.. Create a CNAME record in your vanity domain, pointing to your private space FQDN.
+
Your registrar might take up to 24 hours to apply the change.

. Verify that your account has CloudHub Network Administrator permission, which is required to modify a private space.
+
For information, see xref:access-management::teams.adoc[].


[[create-tls-context]]
== Create a TLS Context

To create a new TLS context:

// SELECT PRIVATE SPACE SHARED
include::partial$select-private-space.adoc[tag=selectPrivateSpace]
include::partial$select-private-space.adoc[tag=clickPrivateSpaceName]
. Click the *Domains & TLS* tab and then click *Create TLS Context*.
+
If you don't have CloudHub Network Administrator permission,
the *Create TLS Context* button is not available.
. Enter a name for the TLS context.
+
The TLS context name can contain letters, numbers, spaces, and hyphens.
. *Configure the keystore:*
+
--
PEM format::
. Select *Upload PEM files*.
. Click *Choose file* and select a public certificate to upload.
+
Uploading the public certificate displays a summary of the certificate.
+
* Click *...* > *View Details* to display the keystore details.
// +
// <screenshot>
* Click *...* > *Delete* to delete the public certificate.

. Click *Choose file* and select a private key to upload.
. Enter the key password used to access the private key within the keystore.
+
If the private key is unencrypted (plain text), which is not recommended,
leave the *Key Password* field blank.
+
CloudHub 2.0 validates the password against the keystore.
+
. If you have a Certificate Authority (CA) path certificate file,
click *Choose file* to upload it.
+
JKS format::
. Select *Upload JKS file*.
. Click *Choose file* and select a keystore file to upload.
. Enter the password used to access the keystore file.
+
CloudHub 2.0 validates the password against the keystore.
. Select an alias from the drop-down list.
+
Selecting an alias displays a summary of the alias.
+
Click the *i* to display the alias details.
// +
// <screenshot>
. Enter the key password used to access the private key within the keystore.
+
CloudHub 2.0 validates the password against the key.
--
. Follow the steps in <<before-you-begin>> to configure DNS.
. *Configure the truststore (optional):*
+
If you want to use partial client authentication, configure a truststore.
The truststore defines the client certificates to use to enable partial client authentication with the configured keystore.
+
Click *Add Certificates* to upload a certificate file (in PEM format).
+
When you upload a PEM file, CloudHub 2.0 displays the client certificates from the truststore file.
+
** Click *Add Certificates* to upload additional certificate files.
** Click the information icon (*View Details*) to display the details of an individual client certificate.
** Click the trash can icon (*Delete*) to delete an individual client certificate.
** If more than four certificates are uploaded, click *Show all x Certificates* to expand the link.

. *Configure advanced options: (Optional)*
+
If you want to customize ciphers, configure advanced options.
+
.. Click *Advanced Options* to display the cipher configuration.
.. Select either *Use Default Ciphers* or *Customize Ciphers*.
+
If you choose to customize ciphers, CloudHub 2.0 displays the default (selected)
ciphers.
+
** Click *X* to remove a cipher from the list.
** Click *Select* to choose a different cipher from the drop-down list.
. Click *Create TLS Context* or *Cancel* to discard changes.


== View TLS Context Details

// SELECT PRIVATE SPACE SHARED
include::partial$select-private-space.adoc[tag=selectPrivateSpace]
include::partial$select-private-space.adoc[tag=clickPrivateSpaceName]
. On the *Domains & TLS* tab, in a custom TLS section, click the TLS context menu (*...*) and select *View Details*.
// +
// <screenshot>

== Delete a TLS Context

// SELECT PRIVATE SPACE SHARED
include::partial$select-private-space.adoc[tag=selectPrivateSpace]
include::partial$select-private-space.adoc[tag=clickPrivateSpaceName]
. On the *Domains & TLS* tab, in a custom TLS section, click the TLS context menu (*...*) and select *Delete*.
// +
// <screenshot>
+
The *Delete* option appears only if you have CloudHub Network Administrator permission.

== Edit a TLS Context

// SELECT PRIVATE SPACE SHARED
include::partial$select-private-space.adoc[tag=selectPrivateSpace]
include::partial$select-private-space.adoc[tag=clickPrivateSpaceName]
. Click the *Domains & TLS* tab and then click *Edit*.
+
The *Edit* button appears only if you have CloudHub Network Administrator permission.

. *Configure the keystore:*
+
--
PEM format::
. Click *Choose file* to replace the current public certificate with a new public certificate.
+
You can't change the private key or password unless you replace
the public certificate.
+
Uploading the public certificate displays a summary of the certificate.
+
Click the information icon (*View Details*) to display the keystore details.
// +
// <screenshot>
. Choose a private key to upload.
. Enter the password used to access the private key within the keystore.
+
If the key password is unencrypted (plain text), which is not recommended,
leave the *Key Password* field blank.
+
CloudHub 2.0 validates the password against the keystore.
+
. If you have a Certificate Authority (CA) path certificate file,
click *Choose file* to upload it.
+
You can remove and add a CA path certificate without replacing the public certificate.
+
JKS format::
. Click *Choose file* to replace the current keystore file with a new keystore file.
. Enter the password used to access the keystore file.
+
CloudHub 2.0 validates the password against the keystore.
. Select an alias from the drop-down list.
+
You can select a different alias without replacing the keystore file.
+
Selecting an alias displays a summary of the alias.
+
Click the information icon (*View Details*) to display the alias details.
. Enter the key password used to access the private key within the keystore.
+
CloudHub 2.0 validates the password against the key.
--

. *Configure the truststore: (Optional)*
+
If you want to use partial client authentication, configure a truststore.
The truststore defines the client certificates to use to enable partial client authentication with the configured keystore.
+
Click *Add Certificates* to upload a certificate file (in PEM format).
+
When you upload a PEM file, CloudHub 2.0 displays the client certificates from the truststore file.
+
** Click *Add Certificates* to upload additional certificate files.
** Click the information icon (*View Details*) to display the details of an individual client certificate.
** Click the trash can icon (*Delete*) to delete an individual client certificate.
. *Configure advanced options: (Optional)*
+
If you want to customize ciphers, configure advanced options.
+
.. Click *Advanced options* to display the cipher configuration.
.. Select either *Use Default Ciphers* or *Customize Ciphers*.
+
If you choose to customize ciphers, CloudHub 2.0 displays the default (selected)
ciphers.
+
** Click *X* to remove a cipher from the list.
** Click *Select a cipher to add* to choose a different cipher.
. Click *Update TLS Context* or *Cancel* to discard changes.


== See Also

* xref:ch2-deploy-private-space.adoc[]
* xref:ch2-config-endpoints-paths.adoc[]
* xref:mule-runtime::tls-configuration.adoc[]
* https://www.whois.com/[Whois^]