Network Encryption (TLS)

Table of Contents

Supported TLS Cipher Suites
Third-Party Certificate Authorities

The MinIO server supports Transport Layer Security (TLS) encryption of incoming and outgoing traffic. MinIO recommends all MinIO servers run with TLS enabled to ensure end-to-end security of client-server or server-server transmissions.

TLS is the successor to Secure Socket Layer (SSL) encryption. SSL is fully deprecated as of June 30th, 2018. MinIO uses only supported (non-deprecated) TLS protocols (TLS 1.2 and later).

MinIO supports multiple TLS certificates, where the server uses Server Name Indication (SNI) to identify which certificate to use when responding to a client request.

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

https://minio.example.net
https://s3.example.net
https://minio.internal-example.net

MinIO can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SAN). However, this would reveal the internal-example.net hostname to all clients. Instead, you can specify multiple TLS certificates to MinIO for the public and private portions of your infrastructure to mitigate the risk of leaking internal topologies via TLS SAN. When a client connects using a specific hostname, MinIO uses SNI to select the appropriate TLS certificate for that hostname.

MinIO by default searches an OS-specific directory for TLS keys and certificates. For deployments started with a custom TLS directory minio server --certs-dir, use that directory instead of the defaults.

Linux

MinIO looks for TLS keys in the following directory:

${HOME}/.minio/certs

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

Create a subfolder in /certs for each additional domain for which MinIO should present TLS certificates. While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability. Place the TLS private and public key for that domain in the subfolder.

For example:

${HOME}/.minio/certs
  private.key
  public.cert
  s3-example.net/
    private.key
    public.cert
  internal-example.net/
    private.key
    public.cert

OSX

MinIO looks for TLS keys in the following directory:

${HOME}/.minio/certs

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

Create a subfolder in /certs for each additional domain for which MinIO should present TLS certificates. While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability. Place the TLS private and public key for that domain in the subfolder.

For example:

${HOME}/.minio/certs
  private.key
  public.cert
  s3-example.net/
    private.key
    public.cert
  internal-example.net/
    private.key
    public.cert

Windows

MinIO looks for TLS keys in the following directory:

%%USERPROFILE%%\.minio\certs

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

Create a subfolder in \certs for each additional domain for which MinIO should present TLS certificates. While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability. Place the TLS private and public key for that domain in the subfolder.

For example:

%%USERPROFILE%%\.minio\certs
  private.key
  public.cert
  s3-example.net\
    private.key
    public.cert
  internal-example.net\
    private.key
    public.cert

MinIO Console TLS Connectivity

The MinIO Console automatically connects via TLS if the MinIO server supports it. However, the Console by default attempts to connect using the IP address of the MinIO Server.

The MinIO Console may fail to connect and throw login errors if this IP address is not included as a Subject Alternative Name in any configured TLS certificate.

Set the MINIO_SERVER_URL environment variable to a resolvable DNS hostname covered by one of the configured TLS SANs. This allows the Console to properly validate the certificate and connect to MinIO.

Supported TLS Cipher Suites

MinIO supports the following TLS 1.2 and 1.3 cipher suites as supported by Go

Cipher	TLS 1.2	TLS 1.3
`TLS_CHACHA20_POLY1305_SHA256`
`TLS_AES_128_GCM_SHA256`
`TLS_AES_256_GCM_SHA384`
`TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305`
`TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`
`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`

Use ECDSA/EdDSA over RSA when when generating certificates

TLS certificates created using Elliptic Curve Cryptography (ECC) have lower computation requirements compared to RSA. Specifically, MinIO recommends generating ECDSA (e.g. NIST P-256 curve) or EdDSA (e.g. Curve25519) TLS private keys/certificates wherever possible.

Third-Party Certificate Authorities

MinIO by default uses the Operating System’s trusted certificate store for validating TLS certificates presented by a connecting client.

For clients connecting with certificates signed by an untrusted Certificate Authority (CA) (e.g. self-signed, private/internal, etc.), you can provide the necessary CA key for MinIO to explicitly trust:

MinIO by default searches an OS-specific directory for Certificate Authority certificates. For deployments started with a custom TLS directory minio server --certs-dir, use that directory instead of the defaults.

Linux

MinIO looks for Certificate Authority keys in the following directory:

${HOME}/.minio/certs/CAs

OSX

MinIO looks for Certificate Authority keys in the following directory:

${HOME}/.minio/certs/CAs

Windows

MinIO looks for Certificate Authority keys in the following directory:

%%USERPROFILE%%\.minio\certs\CAs