Merge pull request #24601 from meln5674/feature/remote-tls

Support (m)TLS API Socket

docs/source/markdown/podman-system-connection-add.1.md

@@ -35,6 +35,18 @@ Port for ssh destination. The default value is `22`.
 
 Path to the Podman service unix domain socket on the ssh destination host
 
+#### **--tls-ca**=*path*
+
+Path to a PEM file containing the certificate authority bundle to verify the server's certificate against.
+
+#### **--tls-cert**=*path*
+
+Path to a PEM file containing the TLS client certificate to present to the server. `--tls-key` must also be provided.
+
+#### **--tls-key**=*path*
+
+Path to a PEM file containing the private key matching `--tls-cert`. `--tls-cert` must also be provided.
+
 ## EXAMPLE
 
 Add a named system connection:
@@ -55,6 +67,7 @@ $ podman system connection add testing unix:///run/podman/podman.sock
 Add a named system connection to local tcp socket:
 ```
 $ podman system connection add debug tcp://localhost:8080
+
 ```
 Add a connection with a custom port:
 ```
@@ -70,6 +83,11 @@ Add a connection and make it the default:
 ```
 $ podman system connection add --default production root@prod.example.com
 ```
+
+Add a named system connection to remote tcp socket secured via TLS:
+```
+$ podman system connection add secure-debug --tls-cert=tls.crt --tls-key=tls.key --tls-ca=ca.crt tcp://podman.example.com:8443
+```
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-system(1)](podman-system.1.md)**, **[podman-system-connection(1)](podman-system-connection.1.md)**
 

docs/source/markdown/podman-system-connection-list.1.md

@@ -24,6 +24,9 @@ Valid placeholders for the Go template listed below:
 | .Identity       | Path to file containing SSH identity |
 | .Name           | Connection Name/Identifier |
 | .ReadWrite      | Indicates if this connection can be modified using the system connection commands |
+| .TLSCA          | Path to a PEM file containing the certificate authority bundle to verify the server's certificate against. |
+| .TLSCert        | Path to a PEM file containing the certificate authority bundle to verify the server's certificate against. |
+| .TLSKey         | Path to a PEM file containing the private key matching `.TLSCA` |
 | .URI            | URI to podman service. Valid schemes are ssh://[user@]*host*[:port]*Unix domain socket*[?secure=True], unix://*Unix domain socket*, and tcp://localhost[:*port*] |
 
 #### **--quiet**, **-q**

docs/source/markdown/podman-system-service.1.md

@@ -70,10 +70,11 @@ To access the API service inside a container:
 
 Please note that the API grants full access to all Podman functionality, and thus allows arbitrary code execution as the user running the API, with no ability to limit or audit this access.
 The API's security model is built upon access via a Unix socket with access restricted via standard file permissions, ensuring that only the user running the service will be able to access it.
-We *strongly* recommend against making the API socket available via the network (IE, bindings the service to a *tcp* URL).
+TLS can be used to secure this socket by requiring clients to present a certificate signed by a trusted certificate authority ("CA"), as well as to allow the client to verify the identity of the API.
+We *strongly* recommend against making the API socket available via the network (IE, bindings the service to a *tcp* URL) without enabling mutual TLS to authenticate the client.
 Even access via Localhost carries risks - anyone with access to the system will be able to access the API.
 If remote access is required, we instead recommend forwarding the API socket via SSH, and limiting access on the remote machine to the greatest extent possible.
-If a *tcp* URL must be used, using the *--cors* option is recommended to improve security.
+If a *tcp* URL must be used without TLS, using the *--cors* option is recommended to improve security.
 
 ## OPTIONS
 
@@ -90,6 +91,19 @@ Print usage statement.
 The time until the session expires in _seconds_. The default is 5
 seconds. A value of `0` means no timeout, therefore the session does not expire.
 
+#### **--tls-cert**=*path*
+
+Path to a PEM file containing the TLS certificate to present to clients. `--tls-key` must also be provided.
+
+#### **--tls-client-ca**=*path*
+
+Path to a PEM file containing the TLS certificate bundle to validate client connections against.
+Connections that present no certificate or a certificate not signed by one of these certificates will be rejected.
+
+#### **--tls-key**=*path*
+
+Path to a PEM file containing the private key matching `--tls-cert`. `--tls-cert` must also be provided.
+
 The default timeout can be changed via the `service_timeout=VALUE` field in containers.conf.
 See **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** for more information.
 

docs/source/markdown/podman.1.md

@@ -173,6 +173,19 @@ Output logging information to syslog as well as the console (default *false*).
 
 On remote clients, including Mac and Windows (excluding WSL2) machines, logging is directed to the file $HOME/.config/containers/podman.log.
 
+#### **--tls-ca**=*path*
+
+Path to a PEM file containing the certificate authority bundle to verify the server's certificate against.
+
+#### **--tls-cert**=*path*
+
+Path to a PEM file containing the TLS client certificate to present to the server. `--tls-key` must also be provided.
+
+#### **--tls-key**=*path*
+
+Path to a PEM file containing the private key matching `--tls-cert`. `--tls-cert` must also be provided.
+
+
 #### **--tmpdir**=*path*
 
 Path to the tmp directory, for libpod runtime content. Defaults to `$XDG_RUNTIME_DIR/libpod/tmp` as rootless and `/run/libpod/tmp` as rootful.