docs/source/operations/network-encryption.rst

Network Encryption (TLS)

minio

Table of Contents

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

not k8s

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.

k8s

For Kubernetes clusters with a valid TLS Cluster Signing Certificate <minio-k8s-deploy-operator-tls>, the MinIO Kubernetes Operator can automatically generate TLS certificates while deploying <minio-k8s-deploy-minio-tenant-security> or modifying <minio-k8s-modify-minio-tenant-security> a MinIO Tenant. The TLS certificate generation process is as follows:

• The Operator generates a Certificate Signing Request (CSR) associated to the Tenant. The CSR (Certificate Signing Request) includes the appropriate DNS Subject Alternate Names (SANs) for the Tenant services and pods.

  The Operator then waits for CSR (Certificate Signing Request) approval

• The CSR (Certificate Signing Request) waits pending approval. The Kubernetes TLS API can automatically approve the CSR (Certificate Signing Request) if properly configured. Otherwise, a cluster administrator must manually approve the CSR (Certificate Signing Request) before Kubernetes can generate the necessary certificates.

• The Operator applies the generated TLS Certificates to each MinIO Pod in the Tenant.

The Kubernetes TLS API uses the Kubernetes cluster Certificate Authority (CA) signature algorithm when generating new TLS certificates. See minio-TLS-supported-cipher-suites for a complete list of MinIO's supported TLS Cipher Suites and recommended signature algorithms.

By default, Kubernetes places a certificate bundle on each pod at /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. This CA bundle should include the cluster or root CA used to sign the MinIO Tenant TLS certificates. Other applications deployed within the Kubernetes cluster can trust this cluster certificate to connect to a MinIO Tenant using the MinIO service DNS name <concepts/services-networking/dns-pod-service/> (e.g. https://minio.minio-tenant-1.svc.cluster-domain.example:443).

Subject Alternative Name Certificates

If you have a custom Subject Alternative Name (SAN) certificate that is not also a wildcard cert, the TLS certificate SAN must apply to the hostname for its parent node. Without a wildcard, the SAN must match exactly to be able to connect to the tenant.

linux

By default, the MinIO server looks for the TLS keys and certificates for each node in the following directory:

${HOME}/.minio/certs

Where ${HOME} is the home directory of the user running the MinIO Server process. You may need to create the ${HOME}/.minio/certs directory if it does not exist.

For deployments using minio server --certs-dir to set a custom TLS directory, use that directory instead of the default. Also, if the user running the process does not have a home directory, you must specify a directory with --certs-dir.

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.

For example:

${HOME}/.minio/certs
  private.key
  public.crt

You can use the MinIO certgen <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 Subject Alternate Names (SANs) associated to the MinIO Server hosts:

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

Place the generated public.crt and private.key into the /.minio/certs directory to enable TLS for the MinIO deployment. 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.

container

Start the MinIO container with the minio/minio:latest server --certs-dir <minio 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 <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.

macos

The MinIO server searches the following directory for TLS keys and certificates:

${HOME}/.minio/certs

For deployments started with a custom TLS directory minio server --certs-dir, use that directory instead of the defaults.

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.

For example:

${HOME}/.minio/certs
  private.key
  public.crt

Where ${HOME} is the home directory of the user running the MinIO Server process. You may need to create the ${HOME}/.minio/certs directory if it does not exist.

You can use the MinIO certgen <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"

Place the generated public.crt and private.key into the /.minio/certs directory to enable TLS for the MinIO deployment. 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.

windows

The MinIO server searches the following directory for TLS keys and certificates:

%%USERPROFILE%%\.minio\certs

For deployments started with a custom TLS directory minio server --certs-dir, use that directory instead of the defaults.

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.

For example:

%%USERPROFILE%%\.minio\certs
  private.key
  public.crt

Where %%USERPROFILE%% is the location of the User Profile folder of the user running the MinIO Server process.

You can use the MinIO certgen <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.exe -host "localhost,minio-*.example.net"

Place the generated public.crt and private.key into the \.minio\certs directory to enable TLS for the MinIO deployment. 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

k8s

The MinIO Operator supports attaching user-specified TLS certificates when deploying <minio-k8s-deploy-minio-tenant-security> or modifying <minio-k8s-modify-minio-tenant-security> the MinIO Tenant.

These custom certificates support Server Name Indication (SNI), where the MinIO server identifies which certificate to use based on the hostname specified by the connecting client. For example, you can generate certificates signed by your organization's preferred Certificate Authority (CA) and attach those to the MinIO Tenant. Applications which trust that CA (Certificate Authority) can connect to the MinIO Tenant and fully validate the Tenant TLS certificates.

linux

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 (Server Name Indication) 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

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.crt
  s3-example.net/
    private.key
    public.crt
  internal-example.net/
    private.key
    public.crt

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 a 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.

container

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 (Server Name Indication) 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

Start the MinIO container with the minio/minio:latest server --certs-dir <minio 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 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.

macos

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

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.crt
  s3-example.net/
    private.key
    public.crt
  internal-example.net/
    private.key
    public.crt

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 a 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.

windows

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

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.crt
  s3-example.net\
    private.key
    public.crt
  internal-example.net\
    private.key
    public.crt

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 a 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 <7748>) 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 star-fill icon:

TLS 1.3

• TLS_CHACHA20_POLY1305_SHA256 star-fill
• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384

TLS 1.2

• TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 star-fill
• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 star-fill
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 star-fill
• 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

k8s

The MinIO Kubernetes Operator can automatically attach third-party Certificate Authorities when deploying <minio-k8s-deploy-minio-tenant-security> or modifying <minio-k8s-modify-minio-tenant-security> a MinIO Tenant.

You can add, update, or remove CAs from the tenant at any time. You must restart the MinIO Tenant for the changes to the configured CAs to apply.

The Operator places the specified CAs on each MinIO Server pod such that all pods have a consistent set of trusted CAs.

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.

linux

The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.

You can place additional trusted Certificate Authority files in the following directory:

${HOME}/.minio/certs/CAs

Where ${HOME} is the home directory of the user running the MinIO Server process. You may need to create the ${HOME}/.minio/certs directory if it does not exist.

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

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.

container

Start the MinIO container with the minio/minio:latest server --certs-dir <minio 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.

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.

macos

The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.

You can place additional trusted Certificate Authority files in the following directory:

${HOME}/.minio/certs/CAs

Where ${HOME} is the home directory of the user running the MinIO Server process. You may need to create the ${HOME}/.minio/certs directory if it does not exist.

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

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.

windows

The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.

You can place additional trusted Certificate Authority files in the following directory:

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

Where %%USERPROFILE%% is the location of the User Profile folder of the user running the MinIO Server process.

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

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, and Private Certificates

not k8s

For certificates signed by a non-global Certificate Authority, place the appropriate X.509 CA certificate in a {HOME}/.minio/CAs directory:

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

For a self-signed certificate, the Certificate Authority is typically the private key used to sign the cert.

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 cert, MinIO ignores the file and does not enable TLS.

k8s

To use certificates generated by a private Certificate Authority, configure MinIO Operator to trust the TLS connections to the tenants:

1. Create a secret named operator-ca-tls in the minio-operator namespace if one does not already exist.

2. Add a ca.crt key to this secret with the public certificate for your internal CA. If operator-ca-tls already contains external CAs, append the new CA to the existing secret.

3. Add the secret in an externalCaCertSecret property in the Tenant YAML configuration <create-tenant-cli-determine-additional-options>:

spec:

externalCaCertSecret: - name: operator-ca-tls type: kubernetes.io/tls

Once the secret is created, Operator creates a copy in each tenant namespace and mounts its certificates in the tenant pods at /tmp/certs/CAs/.

If the operator-ca-tls secret is updated, Operator replicates the new secret to the corresponding copies in the tenant namespaces. Operator replicates changes in the following files:

• public.crt
• tls.crt
• ca.crt