maddy

  1# TLS configuration
  2
  3## Server-side
  4
  5TLS certificates are obtained by modules called "certificate loaders". 'tls' directive
  6arguments specify name of loader to use and arguments. Due to syntax limitations
  7advanced configuration for loader should be specified using 'loader' directive, see
  8below.
  9
 10```
 11tls file cert.pem key.pem {
 12	protocols tls1.2 tls1.3
 13	curves X25519
 14	ciphers ...
 15}
 16
 17tls {
 18	loader file cert.pem key.pem {
 19		# Options for loader go here.
 20	}
 21	protocols tls1.2 tls1.3
 22	curves X25519
 23	ciphers ...
 24}
 25```
 26
 27### Available certificate loaders
 28
 29- `file` – Accepts argument pairs specifying certificate and then key.
 30  E.g. `tls file certA.pem keyA.pem certB.pem keyB.pem`.
 31  If multiple certificates are listed, SNI will be used.
 32- `acme` – Automatically obtains a certificate using ACME protocol (Let's Encrypt)
 33- `off` – Not really a loader but a special value for tls directive, 
 34  explicitly  disables TLS for endpoint(s).
 35
 36## Advanced TLS configuration
 37
 38**Note: maddy uses secure defaults and TLS handshake is resistant to active downgrade attacks. There is no need to change anything in most cases.**
 39
 40---
 41
 42### protocols _min-version_ _max-version_ | _version_
 43Default: `tls1.0 tls1.3`
 44
 45Minimum/maximum accepted TLS version. If only one value is specified, it will
 46be the only one usable version.
 47
 48Valid values are: `tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`
 49
 50---
 51
 52### ciphers _ciphers..._ 
 53Default: Go version-defined set of 'secure ciphers', ordered by hardware
 54performance
 55
 56List of supported cipher suites, in preference order. Not used with TLS 1.3.
 57
 58Valid values:
 59
 60- `RSA-WITH-RC4128-SHA`
 61- `RSA-WITH-3DES-EDE-CBC-SHA`
 62- `RSA-WITH-AES128-CBC-SHA`
 63- `RSA-WITH-AES256-CBC-SHA`
 64- `RSA-WITH-AES128-CBC-SHA256`
 65- `RSA-WITH-AES128-GCM-SHA256`
 66- `RSA-WITH-AES256-GCM-SHA384`
 67- `ECDHE-ECDSA-WITH-RC4128-SHA`
 68- `ECDHE-ECDSA-WITH-AES128-CBC-SHA`
 69- `ECDHE-ECDSA-WITH-AES256-CBC-SHA`
 70- `ECDHE-RSA-WITH-RC4128-SHA`
 71- `ECDHE-RSA-WITH-3DES-EDE-CBC-SHA`
 72- `ECDHE-RSA-WITH-AES128-CBC-SHA`
 73- `ECDHE-RSA-WITH-AES256-CBC-SHA`
 74- `ECDHE-ECDSA-WITH-AES128-CBC-SHA256`
 75- `ECDHE-RSA-WITH-AES128-CBC-SHA256`
 76- `ECDHE-RSA-WITH-AES128-GCM-SHA256`
 77- `ECDHE-ECDSA-WITH-AES128-GCM-SHA256`
 78- `ECDHE-RSA-WITH-AES256-GCM-SHA384`
 79- `ECDHE-ECDSA-WITH-AES256-GCM-SHA384`
 80- `ECDHE-RSA-WITH-CHACHA20-POLY1305`
 81- `ECDHE-ECDSA-WITH-CHACHA20-POLY1305`
 82
 83---
 84
 85### curves _curves..._
 86Default: defined by Go version
 87
 88The elliptic curves that will be used in an ECDHE handshake, in preference
 89order.
 90
 91Valid values: `p256`, `p384`, `p521`, `X25519`.
 92
 93## Client
 94
 95`tls_client` directive allows to customize behavior of TLS client implementation,
 96notably adjusting minimal and maximal TLS versions and allowed cipher suites,
 97enabling TLS client authentication.
 98
 99```
100tls_client {
101    protocols tls1.2 tls1.3
102    ciphers ...
103    curves X25519
104    root_ca /etc/ssl/cert.pem
105
106    cert /etc/ssl/private/maddy-client.pem
107    key /etc/ssl/private/maddy-client.pem
108}
109```
110
111---
112
113###  protocols _min-version_ _max-version_ | _version_
114Default: `tls1.0 tls1.3`
115
116Minimum/maximum accepted TLS version. If only one value is specified, it will
117be the only one usable version.
118
119Valid values are: `tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`
120
121---
122
123### ciphers _ciphers..._
124Default: Go version-defined set of 'secure ciphers', ordered by hardware
125performance
126
127List of supported cipher suites, in preference order. Not used with TLS 1.3.
128
129See TLS server configuration for list of supported values.
130
131---
132
133### curves _curves..._
134Default: defined by Go version
135
136The elliptic curves that will be used in an ECDHE handshake, in preference
137order.
138
139Valid values: `p256`, `p384`, `p521`, `X25519`.
140
141---
142
143### root_ca _paths..._
144Default: system CA pool
145
146List of files with PEM-encoded CA certificates to use when verifying
147server certificates.
148
149---
150
151###  cert _cert-path_ <br> key _key-path_
152Default: not specified
153
154Present the specified certificate when server requests a client certificate.
155Files should use PEM format. Both directives should be specified.