Network Encryption (TLS)

MinIO supports Transport Layer Security (TLS) 1.2+ encryption of incoming and outgoing traffic.

SSL is Deprecated

TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully deprecated as of June 30th, 2018.

Enabling TLS

The sections below describe how to enable TLS for MinIO. You may use TLS certificates from a well-known Certificate Authority, an internal or private CA, or self-signed certs.

Before beginning, note these important points:

Configure TLS on each node.
Ensure certs are readable by the user who runs the MinIO Server process.
Update MINIO_VOLUMES and any needed services or apps to use an HTTPS URL.

Start the MinIO container with the minio/minio:latest server --certs-dir parameter and specify the path to a directory in which MinIO searches for certificates. You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.

Place the TLS certificates for the default domain (e.g. minio.example.net) in the specified directory, with the private key as private.key and public certificate as public.crt. For example:

/opts/certs
  private.key
  public.crt

You can use the MinIO certgen to mint self-signed certificates for evaluating MinIO with TLS enabled. For example, the following command generates a self-signed certificate with a set of IP and DNS SANs associated to the MinIO Server hosts:

certgen -host "localhost,minio-*.example.net"

You may need to start the container and set a --hostname that matches the TLS certificate DNS SAN.

Move the certificates to the local host machine path that the container mounts to its --certs-dir path. When the MinIO container starts, the server searches the specified location for certificates and uses them to enable TLS. Applications can use the public.crt as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.

If you are reconfiguring an existing deployment that did not previously have TLS enabled, update MINIO_VOLUMES to specify https instead of http. You may also need to update URLs used by applications or clients.

Multiple Domain-Based TLS Certificates

The MinIO server supports multiple TLS certificates, where the server uses Server Name Indication (SNI) to identify which certificate to use when responding to a client request. When a client connects using a specific hostname, MinIO uses SNI to select the appropriate TLS certificate for that hostname.

For example, consider a MinIO deployment reachable through the following hostnames:

https://minio.example.net (default TLS certificates)
https://s3.example.net
https://minio.internal-example.net

Place the TLS certificates for the default domain (e.g. minio.example.net) in the specified directory, with the private key as private.key and public certificate as public.crt. For other hostnames, create a subfolder whose name matches the domain to improve human readability. Place the TLS private and public key for that domain in the subfolder.

For example:

/opts/certs
  private.key
  public.crt
  s3-example.net/
    private.key
    public.crt
  internal-example.net/
    private.key
    public.crt

When the MinIO container starts, the server searches the mounted location /opts/certs for certificates and uses them enable TLS. MinIO serves clients connecting to the container using a supported hostname with the associated certificates. Applications can use the public.crt as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.

While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SANs), this would reveal the internal-example.net and s3-example.net hostnames to any client which inspects the server certificate. Using one TLS certificate per hostname better protects each individual hostname from discovery. The individual TLS certificate SANs must apply to the hostname for their respective parent node.

If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.

Supported TLS Cipher Suites

MinIO recommends generating ECDSA (e.g. NIST P-256 curve) or EdDSA (e.g. Curve25519) TLS private keys/certificates due to their lower computation requirements compared to RSA.

MinIO supports the following TLS 1.2 and 1.3 cipher suites as supported by Go. The lists mark recommended algorithms with a icon:

TLS 1.3

TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384

TLS 1.2

TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Third-Party Certificate Authorities

For deployments started with a custom TLS directory minio server --certs-dir, the server searches in the /CAs path at that specified directory. For example:

/opts/certs
  private.key
  public.crt
  /CAs
    my-ca.crt

Place the certificate file for each CA into the /CAs subdirectory. Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory. If the MinIO Server cannot match an incoming client’s TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.

Self-signed, Internal, Private Certificates, and Public CAs with Intermediate Certificates

If using Certificates signed by a non-global or non-public Certificate Authority, or if using a global CA that requires the use of intermediate certificates, you must provide those CAs to the MinIO Server. If the MinIO server does not have the necessary CAs, it may return warnings or errors related to TLS validation when connecting to other services.

Place the CA certificates in the /certs/CAs folder. The root path for this folder depends on whether you use the default certificate path or a custom certificate path (minio server --certs-dir or -S)

Default Certificate Path

mv myCA.crt ${HOME}/.minio/certs/CAs

Custom Certificate Path

The following example assumes the MinIO Server was started with --certs dir /opt/minio/certs:

mv myCA.crt /opt/minio/certs/CAs/

Important

Do not use or share the private key of the self-signed certificate. Only the public certificate should be shared or distributed for trust purposes.

For certificates signed by an internal, private, or other non-global Certificate Authority, use the same CA that signed the cert. A non-global CA must include the full chain of trust from the intermediate certificate to the root.

If the provided file is not an X.509 certificate, MinIO ignores it and may return errors for validating certificates signed by that CA.