Skip to content

Commit 9c13912

Browse files
author
Brice Fallon-Freeman
authored
Merge pull request openshift#3398 from bfallonf/ipsec
Added IPsec file
2 parents 75058c7 + b983b9c commit 9c13912

File tree

2 files changed

+181
-0
lines changed

2 files changed

+181
-0
lines changed

‎_topic_map.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -510,6 +510,9 @@ Topics:
510510
- Name: Sysctls
511511
File: sysctls
512512
Distros: openshift-origin,openshift-enterprise
513+
- Name: Encrypting Hosts with IPsec
514+
File: ipsec
515+
Distros: openshift-origin,openshift-enterprise
513516
- Name: Building Dependency Trees
514517
File: building_dependency_trees
515518
Distros: openshift-origin,openshift-enterprise

‎admin_guide/ipsec.adoc

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
[[admin-guide-ipsec]]
2+
= Encrypting Hosts with IPsec
3+
{product-author}
4+
{product-version}
5+
:data-uri:
6+
:icons:
7+
:experimental:
8+
:toc: macro
9+
:toc-title:
10+
11+
toc::[]
12+
13+
== Overview
14+
15+
IPsec protects traffic in an {product-title} cluster by encrypting the
16+
communication between all master and node hosts that communicate using the
17+
Internet Protocol (IP).
18+
19+
This topic shows how to secure communication of an entire IP subnet from which
20+
the {product-title} hosts receive their IP addresses, including all cluster
21+
management and pod data traffic.
22+
23+
[NOTE]
24+
====
25+
Because {product-title} management traffic uses HTTPS, enabling IPsec encrypts
26+
management traffic a second time.
27+
====
28+
29+
[IMPORTANT]
30+
====
31+
This procedure should be repeated on each master host, then node host, in your
32+
cluster. Hosts that does not have IPsec enabled will not be able to communicate
33+
with a host that does.
34+
====
35+
36+
[[admin-guide-ipsec-encrypting-hosts]]
37+
== Encrypting Hosts
38+
39+
[[admin-guide-ipsec-prerequisites]]
40+
=== Step 1: Prerequisites
41+
Ensure that the *libreswan* package, version 3.19 or later, is installed
42+
on cluster hosts. Only version 3.19 and later includes the necessary
43+
opportunistic group functionality that allows hosts to be configured without
44+
knowledge of every other host in the cluster.
45+
46+
[[admin-guide-ipsec-certificates]]
47+
=== Step 2: Certificates
48+
By default, {product-title} secures cluster management communication with
49+
mutually authenticated HTTPS communication. This means that both the client (for
50+
example, an {product-title} node) and the server (for example, an
51+
{product-title} api-server) send each other their certificates, which are
52+
checked against a known certificate authority (CA). These certificates are
53+
generated at cluster set up time, and typically live on each host.
54+
55+
These certificates can also be used to secure pod communications with IPsec. You
56+
need three files on each host:
57+
58+
* Cluster CA file
59+
* Host client certificate file
60+
* Host private key file
61+
62+
. Determine what the certificate's nickname will be after it has been
63+
imported into the *libreswan* certificate database. The nickname is taken
64+
directly from the certificate's subject's Common Name (CN):
65+
+
66+
----
67+
# openssl x509 \
68+
-in /path/to/client-certificate -subject -noout | \
69+
sed -n 's/.*CN=\(.*\)/\1/p'
70+
----
71+
72+
. Use *openssl* to combine the client certificate, CA certificate, and private
73+
key files into a *_PKCS#12_* file, which is a common file format for multiple
74+
certificates and keys:
75+
+
76+
----
77+
openssl pkcs12 -export \
78+
-in /path/to/client-certificate \
79+
-inkey /path/to/private-key \
80+
-certfile /path/to/certificate-authority \
81+
-passout pass: \
82+
-out certs.p12
83+
----
84+
85+
. Import the *_PKCS#12_* file into the *libreswan* certificate database. The
86+
`-W` option is left empty, because no password is assigned to the *_PKCS#12_*
87+
file, as it is only temporary.
88+
+
89+
----
90+
# ipsec initnss
91+
# pk12util -i certs.p12 -d sql:/etc/ipsec.d -W ""
92+
# rm certs.p12
93+
----
94+
95+
[[admin-guide-ipsec-ipsec-policy]]
96+
=== Step 3: libreswan IPsec Policy
97+
Now that the necessary certificates are imported into the *libreswan*
98+
certificate database, create a policy that uses them to secure communication
99+
between hosts in your cluster.
100+
101+
The following configuration creates two *libreswan* connections. The first
102+
encrypts traffic using the {product-title} certificates, while the second
103+
creates exceptions to the encryption for cluster-external traffic.
104+
105+
. Place the following into the *_/etc/ipsec.d/openshift-cluster.conf_* file:
106+
+
107+
----
108+
conn private
109+
left=%defaultroute
110+
leftid=%fromcert
111+
# our certificate
112+
leftcert="NSS Certificate DB:<cert_nickname>" <1>
113+
right=%opportunisticgroup
114+
rightid=%fromcert
115+
# their certificate transmitted via IKE
116+
rightca=%same
117+
ikev2=insist
118+
authby=rsasig
119+
failureshunt=drop
120+
negotiationshunt=hold
121+
auto=ondemand
122+
123+
conn clear
124+
left=%defaultroute
125+
right=%group
126+
authby=never
127+
type=passthrough
128+
auto=route
129+
priority=100
130+
----
131+
<1> Replace <cert_nickname> with the certificate nickname from step one.
132+
133+
. Tell *libreswan*
134+
which IP subnets and hosts to apply each policy using policy
135+
files in *_/etc/ipsec.d/policies/_*, where each configured connection has a
136+
corresponding policy file. So, in the example above, the two connections,
137+
`private` and `clear`, each have a file in *_/etc/ipsec.d/policies/_*.
138+
+
139+
*_/etc/ipsec.d/policies/private_* should contain the IP subnet of your cluster,
140+
which your hosts receive IP addresses from. By default, this causes all
141+
communication between hosts in the cluster subnet to be encrypted if the remote
142+
host's client certificate authenticates against the local host's Certificate
143+
Authority certificate. If the remote host's certificate does not authenticate,
144+
all traffic between the two hosts will be blocked.
145+
+
146+
For example, if all hosts are configured to use addresses in the `172.16.0.0/16`
147+
address space, your `private` policy file would contain `172.16.0.0/16`. Any
148+
number of additional subnets to encrypt may be added to this file, which results
149+
in all traffic to those subnets using IPsec as well.
150+
151+
. Unencrypt the encryption between all hosts and the subnet gateway to ensure
152+
that traffic can enter and exit the cluster. Add the gateway to the
153+
*_/etc/ipsec.d/policies/clear_* file:
154+
+
155+
----
156+
172.16.0.1/32
157+
----
158+
+
159+
Additional hosts and subnets may be added to this file, which will result in
160+
all traffic to these hosts and subnets being unencrypted.
161+
162+
. Restart the *libreswan* service to load the new configuration and policies,
163+
and begin encrypting:
164+
+
165+
----
166+
systemctl restart ipsec
167+
----
168+
169+
[[admin-guide-ipsec-troubleshooting]]
170+
== Troubleshooting
171+
When authentication cannot be completed between two hosts, you will not be able
172+
to ping between them, because all IP traffic will be rejected. If the `clear`
173+
policy is not configured correctly, you will also not be able to SSH to the host
174+
from another host in the cluster.
175+
176+
You can use the `ipsec status` command to check that the `clear` and `private`
177+
policies have been loaded.
178+

0 commit comments

Comments
 (0)