1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="https">
<title>SSL/TLS Usage</title>
<para>Cockpit usually requires that web browsers communicate with it using HTTPS,
for security reasons.</para>
<section id="https-required">
<title>HTTPS Requirement</title>
<para>Cockpit listens for both HTTP and HTTPS connections on the same port, by
default 9090. If an HTTP connection is made, Cockpit will redirect that
connection to HTTPS. There are some exceptions:</para>
<itemizedlist>
<listitem><para>If an HTTP connection comes from <code>127.0.0.0/8</code>, then
Cockpit will allow communication without redirecting to HTTPS.</para></listitem>
<listitem><para>Certain URLs, like <code>/ping</code> are not required to use
HTTPS.</para></listitem>
</itemizedlist>
<para>This behavior can be overridden by setting the
<code>AllowUnencrypted</code> option in <code>cockpit.conf</code>.</para>
</section>
<section id="https-certificates">
<title>Certificates</title>
<para>Cockpit will load a certificate from the <code>/etc/cockpit/ws-certs.d</code>
directory. It will use the last file with a <code>.cert</code> or <code>.crt</code>
extension in alphabetical order. The file should contain one or more OpenSSL
style <literal>BEGIN CERTIFICATE</literal> blocks for the server certificate and
the intermediate certificate authorities.</para>
<para>The private key can either be contained in the same <code>.cert</code>/<code>.crt</code>
file as an additional <literal>BEGIN PRIVATE KEY</literal> or similar block, or in
a separate file with the same name as the certificate, but with a <code>.key</code>
suffix instead. The key must not be encrypted. For example, a merged file looks like this:</para>
<programlisting>
-----BEGIN CERTIFICATE-----
MIIDUzCCAjugAwIBAgIJAPXW+CuNYS6QMA0GCSqGSIb3DQEBCwUAMD8xKTAnBgNV
BAoMIGI0OGE2NGNkNmMwNTQ1YThhZTgxOTEzZDE5YmJjMmRjMRIwEAYDVQQDDAls
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDUzCCAjugAwIBAgIJAPXW+CuNYS6QMA0GCSqGSIb3DQEBCwUAMD8xKTAnBgNV
BAoMIGI0OGE2NGNkNmMwNTQ1YThhZTgxOTEzZDE5YmJjMmRjMRIwEAYDVQQDDAls
...
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCyOJ5garOYw0sm
8TBCDSqQ/H1awGMzDYdB11xuHHsxYS2VepPMzMzryHR137I4dGFLhvdTvJUH8lUS
...
-----END PRIVATE KEY-----
</programlisting>
<para>Note that for EC keys, the <literal>BEGIN EC PARAMETERS</literal> block must occur
<emphasis>before</emphasis> the <literal>BEGIN EC PRIVATE KEY</literal> block (this
is how OpenSSL, LetsEncrypt, etc. generate the key files).</para>
<para>If no certificate is found, a self-signed certificate is created and
stored in the <filename>0-self-signed.cert</filename> file. On some
platforms, Cockpit will also generate a ca.crt in that directory, which
may be safely imported into client browsers.</para>
<para>To check which certificate <code>cockpit-ws</code> will use run
the following command.</para>
<programlisting>
$ sudo remotectl certificate
</programlisting>
<para>If using <code>certmonger</code> to manage certificates, following command can
be used to automatically prepare concatenated .cert file:</para>
<programlisting>
CERT_FILE=/etc/pki/tls/certs/$(hostname).pem
KEY_FILE=/etc/pki/tls/private/$(hostname).key
getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn) -C "sed -n w/etc/cockpit/ws-certs.d/50-from-certmonger.cert ${CERT_FILE} ${KEY_FILE}"
</programlisting>
</section>
</chapter>
|
