openshift-docs/modules/proxy-certificates.adoc

// Module included in the following assemblies:
//
// * security/certificate-types-descriptions.adoc

[id="proxy-certificates_{context}"]
= Proxy certificates

[discrete]
== Purpose

Proxy certificates allow users to specify one or more custom certificate
authority (CA) certificates used by platform components when making egress
connections.

The `trustedCA` field of the Proxy object is a reference to a ConfigMap that
contains a user-provided trusted certificate authority (CA) bundle. This bundle
is merged with the {op-system-first} trust bundle and injected into the trust
store of platform components that make egress HTTPS calls. For example,
`image-registry-operator` calls an external image registry to download images.
If `trustedCA` is not specified, only the {op-system} trust bundle is used for proxied
HTTPS connections. Provide custom CA certificates to the {op-system} trust bundle if
you want to use your own certificate infrastructure.

The `trustedCA` field should only be consumed by a proxy validator. The
validator is responsible for reading the certificate bundle from required key
`ca-bundle.crt` and copying it to a ConfigMap named `trusted-ca-bundle` in the
`openshift-config-managed` namespace. The namespace for the ConfigMap referenced
by `trustedCA` is `openshift-config`:

[source,yaml]
----
apiVersion: v1
	kind: ConfigMap
 metadata:
	name: user-ca-bundle
	namespace: openshift-config
	data:
	  ca-bundle.crt: |
    -----BEGIN CERTIFICATE-----
    Custom CA certificate bundle.
    -----END CERTIFICATE-----
----

[discrete]
== Managing proxy certificates during installation

The `additionalTrustBundle` value of the installer configuration is used to
specify any proxy-trusted CA certificates during installation. For example:

[source,terminal]
----
$ cat install-config.yaml
----

.Example output
[source,terminal]
----
...
proxy:
  httpProxy: http://<https://username:password@proxy.example.com:123/>
  httpsProxy: https://<https://username:password@proxy.example.com:123/>
	noProxy: <123.example.com,10.88.0.0/16>
additionalTrustBundle: |
    -----BEGIN CERTIFICATE-----
   <MY_HTTPS_PROXY_TRUSTED_CA_CERT>
    -----END CERTIFICATE-----
...
----

[discrete]
== Location

The user-provided trust bundle is represented as a ConfigMap. The ConfigMap is
mounted into the file system of platform components that make egress HTTPS
calls. Typically, Operators mount the ConfigMap to
`/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`, but this is not required by
the proxy. A proxy can modify or inspect the HTTPS connection. In either case,
the proxy must generate and sign a new certificate for the connection.

Complete proxy support means connecting to the specified proxy and trusting any
signatures it has generated. Therefore, it is necessary to let the user specify
a trusted root, such that any certificate chain connected to that trusted root
is also trusted.

If using the RHCOS trust bundle, place CA certificates in
`/etc/pki/ca-trust/source/anchors`.

See
link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-shared-system-certificates_security-hardening[Using
shared system certificates] in the Red Hat Enterprise Linux documentation for
more information.

[discrete]
== Expiration

The user sets the expiration term of the user-provided trust bundle.

The default expiration term is defined by the CA certificate itself. It is up to
the CA administrator to configure this for the certificate before it can be used
by {product-title} or {op-system}.

[NOTE]
====
Red Hat does not monitor for when CAs expire. However, due to the long life of
CAs, this is generally not an issue. However, you might need to periodically
update the trust bundle.
====

[discrete]
== Services

By default, all platform components that make egress HTTPS calls will use the
{op-system} trust bundle. If `trustedCA` is defined, it will also be used.

Any service that is running on the {op-system} node is able to use the trust bundle of
the node.

[discrete]
== Management

These certificates are managed by the system and not the user.

[discrete]
== Customization

Updating the user-provided trust bundle consists of either:

* updating the PEM-encoded certificates in the ConfigMap referenced by
`trustedCA,` or
* creating a ConfigMap in the namespace `openshift-config` that contains the new
trust bundle and updating `trustedCA` to reference the name of the new
ConfigMap.

The mechanism for writing CA certificates to the {op-system} trust bundle is exactly
the same as writing any other file to {op-system}, which is done through the use of
MachineConfigs. When the Machine Config Operator (MCO) applies the new
MachineConfig that contains the new CA certificates, the node is rebooted.
During the next boot, the service `coreos-update-ca-trust.service` runs on the
{op-system} nodes, which automatically update the trust bundle with the new CA
certificates. For example:

[source,yaml]
----
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfig
metadata:
  labels:
    machineconfiguration.openshift.io/role: worker
  name: 50-examplecorp-ca-cert
spec:
  config:
    ignition:
      version: 3.1.0
    storage:
      files:
      - contents:
          source: data:text/plain;charset=utf-8;base64,LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVORENDQXh5Z0F3SUJBZ0lKQU51bkkwRDY2MmNuTUEwR0NTcUdTSWIzRFFFQkN3VUFNSUdsTVFzd0NRWUQKV1FRR0V3SlZVekVYTUJVR0ExVUVDQXdPVG05eWRHZ2dRMkZ5YjJ4cGJtRXhFREFPQmdOVkJBY01CMUpoYkdWcApBMmd4RmpBVUJnTlZCQW9NRFZKbFpDQklZWFFzSUVsdVl5NHhFekFSQmdOVkJBc01DbEpsWkNCSVlYUWdTVlF4Ckh6QVpCZ05WQkFNTUVsSmxaQ0JJWVhRZ1NWUWdVbTl2ZENCRFFURWhNQjhHQ1NxR1NJYjNEUUVKQVJZU2FXNW0KWGpDQnBURUxNQWtHQTFVRUJoTUNWVk14RnpBVkJnTlZCQWdNRGs1dmNuUm9JRU5oY205c2FXNWhNUkF3RGdZRApXUVFIREFkU1lXeGxhV2RvTVJZd0ZBWURWUVFLREExU1pXUWdTR0YwTENCSmJtTXVNUk13RVFZRFZRUUxEQXBTCkFXUWdTR0YwSUVsVU1Sc3dHUVlEVlFRRERCSlNaV1FnU0dGMElFbFVJRkp2YjNRZ1EwRXhJVEFmQmdrcWhraUcKMHcwQkNRRVdFbWx1Wm05elpXTkFjbVZrYUdGMExtTnZiVENDQVNJd0RRWUpLb1pJaHZjTkFRRUJCUUFEZ2dFUApCRENDQVFvQ2dnRUJBTFF0OU9KUWg2R0M1TFQxZzgwcU5oMHU1MEJRNHNaL3laOGFFVHh0KzVsblBWWDZNSEt6CmQvaTdsRHFUZlRjZkxMMm55VUJkMmZRRGsxQjBmeHJza2hHSUlaM2lmUDFQczRsdFRrdjhoUlNvYjNWdE5xU28KSHhrS2Z2RDJQS2pUUHhEUFdZeXJ1eTlpckxaaW9NZmZpM2kvZ0N1dDBaV3RBeU8zTVZINXFXRi9lbkt3Z1BFUwpZOXBvK1RkQ3ZSQi9SVU9iQmFNNzYxRWNyTFNNMUdxSE51ZVNmcW5obzNBakxRNmRCblBXbG82MzhabTFWZWJLCkNFTHloa0xXTVNGa0t3RG1uZTBqUTAyWTRnMDc1dkNLdkNzQ0F3RUFBYU5qTUdFd0hRWURWUjBPQkJZRUZIN1IKNXlDK1VlaElJUGV1TDhacXczUHpiZ2NaTUI4R0ExVWRJd1FZTUJhQUZIN1I0eUMrVWVoSUlQZXVMOFpxdzNQegpjZ2NaTUE4R0ExVWRFd0VCL3dRRk1BTUJBZjh3RGdZRFZSMFBBUUgvQkFRREFnR0dNQTBHQ1NxR1NJYjNEUUVCCkR3VUFBNElCQVFCRE52RDJWbTlzQTVBOUFsT0pSOCtlbjVYejloWGN4SkI1cGh4Y1pROGpGb0cwNFZzaHZkMGUKTUVuVXJNY2ZGZ0laNG5qTUtUUUNNNFpGVVBBaWV5THg0ZjUySHVEb3BwM2U1SnlJTWZXK0tGY05JcEt3Q3NhawpwU29LdElVT3NVSks3cUJWWnhjckl5ZVFWMnFjWU9lWmh0UzV3QnFJd09BaEZ3bENFVDdaZTU4UUhtUzQ4c2xqCjVlVGtSaml2QWxFeHJGektjbGpDNGF4S1Fsbk92VkF6eitHbTMyVTB4UEJGNEJ5ZVBWeENKVUh3MVRzeVRtZWwKU3hORXA3eUhvWGN3bitmWG5hK3Q1SldoMWd4VVp0eTMKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo=
        mode: 0644
        overwrite: true
        path: /etc/pki/ca-trust/source/anchors/examplecorp-ca.crt
----

The trust store of machines must also support updating the trust store of nodes.

[discrete]
== Renewal

There are no Operators that can auto-renew certificates on the {op-system} nodes.

[NOTE]
====
Red Hat does not monitor for when CAs expire. However, due to the long life of
CAs, this is generally not an issue. However, you might need to periodically
update the trust bundle.
====