felixauringer commented on code in PR #3040:
URL: https://github.com/apache/james-project/pull/3040#discussion_r3248233276
##########
docs/modules/servers/partials/configure/ssl.adoc:
##########
@@ -1,55 +1,194 @@
-This document explains how to enable James 3.0 servers to use Transport Layer
Security (TLS)
-for encrypted client-server communication.
+The servers
+xref:{pages-path}/configure/smtp.adoc[SMTP],
+xref:{pages-path}/configure/pop3.adoc[POP3],
+xref:{pages-path}/configure/imap.adoc[IMAP], and
+xref:{pages-path}/configure/sieve.adoc[Managesieve]
+support TLS.
+The configuration is the same for all of them and this document explains how
to do it.
-== Configure a Server to Use SSL/TLS
+== Configure a Server to Use TLS
-Each of the servers xref:{pages-path}/configure/smtp.adoc[SMTP - LMTP],
-xref:{pages-path}/configure/pop3.adoc[POP3] and
xref:{pages-path}/configure/imap.adoc[IMAP]
-supports use of SSL/TLS.
+As described in xref:{pages-path}/configure/server.adoc[SMTP],
+there is a `tls` element inside the XML server element.
-TLS (Transport Layer Security) and SSL (Secure Sockets Layer) are protocols
that provide
-data encryption and authentication between applications in scenarios where
that data is
-being sent across an insecure network, such as checking your email
-(How does the Secure Socket Layer work?). The terms SSL and TLS are often used
-interchangeably or in conjunction with each other (TLS/SSL),
-but one is in fact the predecessor of the other — SSL 3.0 served as the basis
-for TLS 1.0 which, as a result, is sometimes referred to as SSL 3.1.
+It supports two attributes:
-You need to add a block in the corresponding configuration file
(smtpserver.xml, pop3server.xml, imapserver.xml,..)
+- `socketTLS`: Enables STARTTLS for this server. The client can upgrade the
connection using the `STARTTLS` command.
+- `startTLS`: Enables implicit TLS on this port.
+
+By default, both attributes are `false`.
+However, it is highly recommended to use TLS and set one of these to `true`
for every server.
+They can not both be `true` for one server.
+
+Additionally, the `tls` element can have the following child elements.
+There are also examples after the table.
+
+.`tls` element
+|===
+| Property Name | Explanation
+
+| `supportedCipherSuites`
+| Contains the ciphersuites that should be enabled.
+Every ciphersuite is in its own `cipherSuite` element.
+If not configured, the library's default is used.
+
+| `supportedProtocols`
+| Contains the protocols that should be enabled.
+Every protocol is in its own `protocol` element.
+If not configured, the library's default is used.
+
+| `keystore`
+| The path to a keystore.
+The keystore **must** have only one certificate.
+Either the keystore or both private key and certificates must be configured.
+
+| `keystoreType`
+| The type of the keystore.
+It is an optinal string with the default value `JKS`.
+A common alternative is `PKCS12`.
+
+| `privateKey`
+| The path to a private key.
+If configured, `certificates` must also be configured.
+
+| `certificates`
+| A path to a certificate bundle.
+The last certificate in the bundle is the one signed by a root CA.
+If configured, `privateKey` must also be configured.
+
+| `secret`
+| A secret for the keystore or private key.
+It is optional.
+
+| `clientAuth`
+a| Configures TLS client authentication.
+If this is present, all clients are required to authenticate on the TLS level.
+It has the following child elements:
+
+- `clientAuth.truststore`: An optional path to the truststore for verifying
client certificates. The truststore can contain client certificates directly or
CAs that issued client certificates. If not configured, the library's default
is used.
+- `clientAuth.truststoreType`: The type of the keystore. It is optional and
defaults to `JKS`.
+- `clientAuth.truststoreSecret`: An optional secret for the truststore.
+
+| `enableOCSPCRLChecks`
+| Enables revocation checks for client authentication.
+It is an optional boolean that is `false` by default.
+
+| `sessionCache.size`
+| Sets the maximum number of TLS sessions in the session cache.
+If not configured, the library's default is used.
+
+| `sessionCache.timeout`
+| Sets the duration after which TLS sessions in the cache time out.
+If not configured, the library's default is used.
+It is an integer followed by an optional unit.
+The default unit is `ms` (millisecond) and other reasonable values are `s`
(second) or `m` (minute).
+
+|===
+
+The paths in the table above are usually file paths and prefixed with
`file://`.
+They can either be relative (e.g., `file://conf/imap.crt`) or absolute (e.g.,
`file:///james/conf/imap.crt`).
+
+== TLS for Email Services
+
+Email was established before protocols like TLS that can secure TCP
connections independent of the application layer.
+Therefore, the email services on the initially established ports never had a
security layer.
+Because of backward compatibility, this will not change.
+STARTTLS was introduced to negotiate a security layer over the insecure
channel.
+For it to work, both the server and the client must abort sessions if STARTTLS
is not used.
+
+Alternatively, other ports that are expected to use implicit TLS have been
established by RFC 8314.
+
+.Ports for email services
+|===
+| Service | Client | Ports
+
+| SMTP
+| Remote MX
+| insecure: 25, TLS: not defined by RFC
+
+When trying to deliver emails to another email server using implicit TLS,
James attempts to use port 465.
+
+| SMTP Submission
+| MUA
+| insecure: 587, TLS: 465
+
+| IMAP
+| MUA
+| insecure: 143, TLS: 993
+
+| POP3
+| MUA
+| insecure: 110, TLS: 995
+
+| LMTP
+| Local MX
+| insecure: 24, no TLS port defined
+
+TLS for LMTP is not supported by James.
Review Comment:
Should be relatively easy because the LMTP server extends an abstract server
that supports it and just does not call `getEncryption`.
However, we have no use for this feature and I personally do not really know
the LMTP codebase and have no idea what implications this change would have. I
am not even sure whether STARTTLS is a thing with LMTP.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
