[online-3.7] Document TLS and crypto settings

architecture/index.adoc

@@ -38,6 +38,7 @@ to manage services.
 endif::[]
 ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[]
 
+[[arch-index-what-are-the-layers]]
 == What Are the Layers?
 
 The Docker service provides the abstraction for packaging and creating
@@ -62,6 +63,7 @@ as they flow through your system
 image::architecture_overview.png[{product-title} Architecture Overview]
 endif::[]
 
+[[arch-index-what-is-the-architecture]]
 == What Is the {product-title} Architecture?
 
 {product-title} has a microservices-based architecture of smaller, decoupled units
@@ -111,15 +113,17 @@ restart the affected components, and the system double checks everything before
 continuing. The system should eventually converge to the user's intent, since
 the controllers can always bring the system into sync.
 
+[[arch-index-how-is-it-secured]]
 == How Is {product-title} Secured?
 
 The {product-title} and Kubernetes APIs
 xref:additional_concepts/authentication.adoc#architecture-additional-concepts-authentication[authenticate] users who present
 credentials, and then xref:additional_concepts/authorization.adoc#architecture-additional-concepts-authorization[authorize]
 them based on their role. Both developers and administrators can be
 authenticated via a number of means, primarily
-xref:additional_concepts/authentication.adoc#oauth[OAuth tokens] and SSL
-certificate authorization.
+xref:additional_concepts/authentication.adoc#oauth[OAuth tokens] and X.509
+client certificates. OAuth tokens are signed with JSON Web Algorithm
+_RS256_, which is RSA signature algorithm PKCS#1 v1.5 with SHA-256.
 
 Developers (clients of the system) typically make REST API calls from a
 xref:../cli_reference/index.adoc#cli-reference-index[client program] like `oc` or to the
@@ -138,11 +142,101 @@ checks for one or more of the roles assigned to the user (e.g., cluster
 administrator or administrator of the current project) before allowing it to
 continue.
 
-ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[]
+ifdef::openshift-origin,openshift-online,openshift-enterprise[]
 Since every container that runs on the cluster is associated with a service
 account, it is also possible to associate
 xref:../dev_guide/secrets.adoc#dev-guide-secrets[secrets] to those service accounts and have them
 automatically delivered into the container. This enables the infrastructure to
 manage secrets for pulling and pushing images, builds, and the deployment
 components, and also allows application code to easily leverage those secrets.
 endif::[]
+
+[[arch-index-how-is-it-secured-tls]]
+=== TLS Support
+
+All communication channels with the REST API, as well as between
+xref:infrastructure_components/kubernetes_infrastructure.adoc#master-components[master components] such as etcd and the API server, are secured with TLS. TLS provides
+strong encryption, data integrity, and authentication of servers with X.509
+server certificates and public key infrastructure.
+ifdef::openshift-origin,openshift-enterprise,openshift-dedicated[]
+By default, a new internal PKI is created for each deployment of
+{product-title}. The internal PKI uses 2048 bit RSA keys and SHA-256 signatures.
+endif::[]
+ifdef::openshift-origin,openshift-enterprise[]
+xref:../install_config/certificate_customization.adoc#install-config-certificate-customization[Custom certificates] for public hosts are supported as well. 
+endif::[]
+
+{product-title} uses Golang’s standard library implementation of
+link:https://golang.org/pkg/crypto/tls/[*crypto/tls*] and does not depend on any
+external crypto and TLS libraries. Additionally, the client depends on external
+libraries for GSSAPI authentication and OpenPGP signatures. GSSAPI is typically
+provided by either MIT Kerberos or Heimdal Kerberos, which both use OpenSSL's
+libcrypto. OpenPGP signature verification is handled by libgpgme and GnuPG.
+
+The insecure versions SSL 2.0 and SSL 3.0 are unsupported and not available. The
+{product-title} server and `oc` client only provide TLS 1.2 by default. TLS 1.0
+and TLS 1.1 can be enabled in the server configuration. Both server and client
+prefer modern cipher suites with authenticated encryption algorithms and perfect
+forward secrecy. Cipher suites with deprecated and insecure algorithms such as
+RC4, 3DES, and MD5 are disabled. Some internal clients (for example, LDAP
+authentication) have less restrict settings with TLS 1.0 to 1.2 and more cipher
+suites enabled.
+
+.Supported TLS Versions
+[cols="4*", options="header"]
+|===
+|TLS Version
+|{product-title} Server
+|`oc` Client
+|Other Clients
+
+|SSL 2.0
+|Unsupported
+|Unsupported
+|Unsupported
+
+|SSL 3.0
+|Unsupported
+|Unsupported
+|Unsupported
+
+|TLS 1.0
+|No footnoteref:[tlsconfig,Disabled by default, but can be enabled in the server configuration.]
+|No footnoteref:[tlsconfig]
+|Maybe footnoteref:[otherclient,Some internal clients, such as the LDAP client.]
+
+|TLS 1.1
+|No footnoteref:[tlsconfig]
+|No footnoteref:[tlsconfig]
+|Maybe footnoteref:[otherclient]
+
+|TLS 1.2
+|*Yes*
+|*Yes*
+|*Yes*
+
+|TLS 1.3
+|N/A footnoteref:[tls13,TLS 1.3 is still under development.]
+|N/A footnoteref:[tls13]
+|N/A footnoteref:[tls13]
+|===
+
+The following list of enabled cipher suites of {product-title}'s server and `oc`
+client are sorted in preferred order:
+
+- `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305`
+- `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305`
+- `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
+- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
+- `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
+- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
+- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`
+- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`
+- `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
+- `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
+- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
+- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
+- `TLS_RSA_WITH_AES_128_GCM_SHA256`
+- `TLS_RSA_WITH_AES_256_GCM_SHA384`
+- `TLS_RSA_WITH_AES_128_CBC_SHA`
+- `TLS_RSA_WITH_AES_256_CBC_SHA`