forked from libreswan/libreswan
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.nss
268 lines (185 loc) · 10.1 KB
/
README.nss
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
#########################################################################
# Using the NSS crypto library with Pluto (Libreswan)
# Based on initial documentation by Avesh Agarwal <avagarwa@redhat.com>
#########################################################################
For detailed developer information about NSS, see
https://www.mozilla.org/projects/security/pki/nss/
The NSS crypto library is a user space library. It is only used with the
libreswan userspace IKE daemon pluto for cryptographic operations. NSS
does not perform IPsec crypto operations inside the kernel (KLIPS
nor NETKEY)
The NSS library exports a PKCS#11 API for the application to
communicate to a cryptographic device. The cryptographic device is
usually the "soft token" but can also be a Hardware Security Module
(HSM).
The advantage of using NSS is that pluto does need to know in detail how
the cryptographic device works. Pluto does not access any private keys or
data itself. Instead, it uses the PK11 wrapper API of NSS irrespective
of the cryptographic device used. Pluto hands over work using the PK11
interface to NSS and never has direct access to the private key material
itself. Both IKEv1 and IKEv2 operations are performed using NSS. Private
RSA keys (raw RSA as well as X.509 based private RSA keys) are stored
inside NSS. RSA keys are still referenced in /etc/ipsec.secrets. X.509
keys and certificates are referenced using their "nickname" instead of
their filename in /etc/ipsec.conf.
While PreShared Key (PSK) calculations are done using NSS, the actual
preshared key ("secret") is still stored in /etc/ipsec.secrets.
NSS as shipped by Red Hat is a FIPS certified library. Libreswan is
currently being FIPS certified for RHEL7.
#########################################################################
# The NSS command line tools used with libreswan
#########################################################################
- certutil: Look and modify the NSS db. "ipsec initnss" and "ipsec look"
use certutil under the hood.
https://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
- pk12util: import and export certificates and keys from and to the NSS db.
The "ipsec import" command is a simple wrapper around this utility.
https://www.mozilla.org/projects/security/pki/nss/tools/pk12util.html
- modutil: Put NSS into FIPS mode
https://www.mozilla.org/projects/security/pki/nss/tools/modutil.html
#########################################################################
# Creating the NSS db for use with libreswan's pluto IKE daemon
#########################################################################
If you are not using a packaged libreswan version, you might need to
create a new NSS db before you can start libreswan. This can be done
using:
ipsec initnss
By default the NSS db is created in /etc/ipsec.d/ on RHEL/Fedora/CentOS
but in /var/lib/ipsec/nss/ on Debian/Ubuntu. The remainder of this file
uses /etc/ipsec.d/ in the examples.
When creating a database, you are prompted for a password. The default
libreswan package install for RHEL/Fedora/CentOS uses an empty password.
It is up to the administrator to decide on whether to use a password
or not. However, a non-empty database password must be provided when
running in FIPS mode.
To change the empty password, run:
certutil -W -d sql:/etc/ipsec.d
Enter return for the "old password", then enter your new password.
If you create the database with a password, and want to run NSS in FIPS
mode, you must create a password file with the name "nsspassword" in
the /etc/ipsec.d direcotry before starting libreswan. The "nsspassword"
file must contain the password you provided when creating NSS database.
If the NSS db is protected with a non-empty password, the "nsspassword"
file must exist for pluto to start.
The syntax of the "nsspassword" file is:
token_1_name:the_password
token_2_name:the_password
The name of NSS softtoken (the default software NSS db) when NOT running
in FIPS mode is "NSS Certificate DB". If you wish to use software NSS
db with password "secret", you would have the following entry in the
nsspassword file:
NSS Certificate DB:secret
If running NSS in FIPS mode, the name of NSS softtoken is
"NSS FIPS 140-2 Certificate DB". If there are smartcards in the system, the
entries for passwords should be entered in this file as well.
Note: do not enter any spaces before or after the token name or password.
#########################################################################
# Using raw RSA keys with NSS
#########################################################################
The "ipsec newhostkey" and "ipsec rsasigkey" utilities are used for
creating raw RSA keys. If a non-default NSS directory is used, this can
be specified using the --nssdir option.
ipsec newhostkey --nssdir /tmp/ipsec.d [--password password]
The password is only required if the NSS database is protected with a
non-empty password.
Public key information is available via the "ipsec showhostkey" command
can be used to generate left/rightrsasigkey= entries for /etc/ipsec.conf.
#########################################################################
# Using certificates with NSS
#########################################################################
Any X.509 certificate management system can be used to generate Certificate
Agencies, certificates, pkcs12 files and CRLs. Common tools people use are
the openssl command, the GTK utility tinyca2, or the NSS certutil command.
An example using openssl can be found as part of the libreswan test suite at
https://github.com/libreswan/libreswan/tree/master/testing/x509
Below, we will be using the nss tools to generate certificates
* To create a certificate authority (CA certificate):
certutil -S -k rsa -n "ExampleCA" -s "CN=Example CA Inc" -v 12 \
-t "CT,," -x -d sql:/etc/ipsec.d
It creates a certificate with RSA keys (-k rsa) with the nickname
"ExampleCA", and with common name "Example CA Inc". The option
"-v" specifies the certificates validy period. "-t" specifies the attributes
of the certificate. "C" is required for creating a CA certificate. "-x" mean
self signed. "-d" specifies the path of the database directory. The directory
path should be prefixed with 'sql:' in order to use the SQLite format.
NOTE: It is not a requirement to create the CA in NSS database. The CA
certificate can be obtained from anywhere in the world.
* To create a user certificate signed by the above CA
certutil -S -k rsa -c "ExampleCA" -n "user1" -s "CN=User Common Name" \
-v 12 -t "u,u,u" -d sql:/etc/ipsec.d
It creates a user cert with nickname "user1" with attributes
"u,u,u" signed by the CA cert "ExampleCA".
NOTE: You must provide a nick name when creating a user certificate,
because pluto reads the user certificate from the NSS database based on
the user certificate's nickname.
#########################################################################
# Configuring certificates in ipsec.conf and ipsec.secrets
#########################################################################
In ipsec.conf, the leftcert= option takes a certificate nickname as argument.
For example if the nickname of the user cert is "hugh", then it can be
"leftcert=hugh".
NOTE: if you are migrating from openswan, you are used to specifying
a filename for the leftcert= option. Filenames
are not valid for the left/rightcert= options in libreswan.
In ipsec.secrets, we need to list the certificate nickname to inform pluto
there is a certificate within the NSS db.
This is specified using:
: RSA nickname
NOTE: In openswan and freeswan it was required to specify a file name or
password. With libreswan, this is not required.
NOTE: openswan and freeswan stored private keys in /etc/ipsec.d/private/
This directory does not exist for libreswan.
The directories /etc/ipsec.d/cacerts/ and /etc/ipsec.d/crls/ can still be used.
NOTE: the freeswan and openswan directories /etc/ipsec.d/aacerts/ and
/etc/ipsec.d/acerts/ are not used with libreswan.
If you use an external CA certificate, you can either import it into
the NSS db or place it in the /etc/ipsec.d/cacerts/ directory. Note that
the preferred method is to store it inside the NSS db.
#########################################################################
# Importing third-party certificates into NSS
#########################################################################
If you do not have the third-party certificate in PKCS#12 format, use openssl
to create a PKCS#12 file:
openssl pkcs12 -export -in cert.pem -inkey key.pem \
-certfile cacert.pem -out certkey.p12 [-name YourName]
Now you can import the file into the NSS db:
ipsec import certkey.p12
If you did not pick a name using the -name option, you can use
certutil -L -d sql:/etc/ipsec.d to figure out the name NSS picked during
the import.
Add following to /etc/ipsec.secrets file:
: RSA "YourName"
To specify the certificate in ipsec.conf, use a line like:
leftcert=YourName
#########################################################################
# Exporting a CA(?) certificate to load on another libreswan machine
#########################################################################
Paul: wouldn't this also include the private key which we don't want?????
Paul: add "ipsec export" ?
To export the CA certificate:
pk12util -o cacert1.p12 -n cacert1 -d sql:/etc/ipsec.d
Copy the file "cacert1.p12" to the new machine and import it using:
ipsec import cacert1.p12
certutil -M -n cacert1 -t "CT,," -d sql:/etc/ipsec.d
Example connection for ipsec.conf:
conn pluto-1-2
left=1.2.3.4
leftid="CN=usercert1"
leftrsasigkey=%cert
leftcert=usercert1
right=5.6.7.8
rightid="CN=usercert2"
rightrsasigkey=%cert
auto=add
#########################################################################
# Configuring a smartcard with NSS
#########################################################################
Required library: libcoolkey
To make smartcard tokens visible through NSS
modutil -add <module_name> -libfile libcoolkeypk11.so \
-dbdir <nss_database_dir_name> \
-mechanisms <mechanisms_separted_by_colons>
An example of mechanisms can be
RC2:RC4:DES:DH:SHA1:MD5:MD2:SSL:TLS:AES:CAMELLIA.
To check whether the token is visible or not, please run
modutil -list -dbdir <nss_database_dir_name>