| blob | e1b54b1a0324c8810732f18f21b965398436a033 |
1 Contributor: Christian Starkjohann <cs@obdev.at>
2 Date: May 29, 1998
3 Status:
5 Comment: Updated by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE>
6 Date: July 16, 2001
8 Subject: Compiling and using samba with SSL support
9 ============================================================================
11 What is SSL and SSLeay/OpenSSL?
12 ===============================
13 SSL (Secure Socket Layer) is a protocol for encrypted and authenticated data
14 transport. It is used by secure web servers for shopping malls, telebanking
15 and things like that.
17 SSLeay is a free implementation of the SSL protocol. The successor of it is
18 OpenSSL, available from
20 http://www.openssl.org/
22 The current version while these lines are written is 0.9.6b. In some countries
23 encryption is plagued by legal problems, even though things have relaxed a
24 lot in the last years.
26 To compile samba with SSL support, you must first compile and install OpenSSL.
27 At least version 0.9.5 of OpenSSL is required. Version 0.9.6b is the latest
28 version and is strongly recommended.
29 OpenSSL consists of a library (which can be linked to other applications like
30 samba) and several utility programs needed for key generation, certification
31 etc. OpenSSL installs to /usr/local/ssl/ by default.
34 Compiling samba with OpenSSL
35 ============================
36 1. Get and install OpenSSL. The rest of this documentation assumes that you
37 have installed it at the default location, which is /usr/local/ssl/.
38 2. Call "configure" with the "--with-ssl" flag. If OpenSSL is not installed in
39 the default directory, you can use the "--with-sslinc" and "--with-ssllib"
40 flags to specify the location.
41 3. Compile and install as usual.
44 Configuring SSL in samba
45 ========================
46 Before you configure SSL, you should know the basics of cryptography and how
47 SSL relates to all of this. A basic introduction can be found further down in
48 this document. The following variables in the "[global]" section of the
49 configuration file are used to configure SSL:
51 ssl = yes
52 This variable enables or disables the entire SSL mode. If it is set to
53 "no", the SSL enabled samba behaves exactly like the non-SSL samba. If set
54 to "yes", it depends on the variables "ssl hosts" and "ssl hosts resign"
55 whether an SSL connection will be required.
56 ssl hosts =
57 ssl hosts resign = 192.168.
58 These two variables define whether samba will go into SSL mode or not. If
59 none of them is defined, samba will allow only SSL connections. If the
60 "ssl hosts" variable lists hosts (by IP-address, IP-address range, net
61 group or name), only these hosts will be forced into SSL mode. If the
62 "ssl hosts resign" variable lists hosts, only these hosts will NOT be
63 forced into SSL mode. The syntax for these two variables is the same as
64 for the "hosts allow" and "hosts deny" pair of variables, only that the
65 subject of the decision is different: It's not the access right but
66 whether SSL is used or not. See the man page of smb.conf (section about
67 "allow hosts") for details. The above example requires SSL connections
68 from all hosts outside the local net (which is 192.168.*.*).
69 ssl CA certDir = /usr/local/ssl/certs
70 This variable defines where to look up the Certification Autorities. The
71 given directory should contain one file for each CA that samba will trust.
72 The file name must be the hash value over the "Distinguished Name" of the
73 CA. How this directory is set up is explained later in this document. All
74 files within the directory that don't fit into this naming scheme are
75 ignored. You don't need this variable if you don't verify client
76 certificates.
77 ssl CA certFile = /usr/local/ssl/certs/trustedCAs.pem
78 This variable is a second way to define the trusted CAs. The certificates
79 of the trusted CAs are collected in one big file and this variable points
80 to the file. You will probably only use one of the two ways to define your
81 CAs. The first choice is preferable if you have many CAs or want to be
82 flexible, the second is perferable if you only have one CA and want to
83 keep things simple (you won't need to create the hashed file names). You
84 don't need this variable if you don't verify client certificates.
85 ssl server cert = /usr/local/ssl/certs/samba.pem
86 This is the file containing the server's certificate. The server _must_
87 have a certificate. The file may also contain the server's private key.
88 See later for how certificates and private keys are created.
89 ssl server key = /usr/local/ssl/private/samba.pem
90 This file contains the private key of the server. If this variable is not
91 defined, the key is looked up in the certificate file (it may be appended
92 to the certificate). The server _must_ have a private key and the
93 certificate _must_ match this private key.
94 ssl client cert = /usr/local/ssl/certs/smbclient.pem
95 The certificate in this file is used by smbclient if it exists. It's needed
96 if the server requires a client certificate.
97 ssl client key = /usr/local/ssl/private/smbclient.pem
98 This is the private key for smbclient. It's only needed if the client
99 should have a certificate.
100 ssl require clientcert = yes
101 If this variable is set to "yes", the server will not tolerate connections
102 from clients that don't have a valid certificate. The directory/file
103 given in "ssl CA certDir" and "ssl CA certFile" will be used to look up
104 the CAs that issued the client's certificate. If the certificate can't be
105 verified positively, the connection will be terminated.
106 If this variable is set to "no", clients don't need certificates. Contrary
107 to web applications you really _should_ require client certificates. In
108 the web environment the client's data is sensitive (credit card numbers)
109 and the server must prove to be trustworthy. In a file server environment
110 the server's data will be sensitive and the clients must prove to be
111 trustworthy.
112 ssl require servercert = yes
113 If this variable is set to "yes", the smbclient will request a certificate
114 from the server. Same as "ssl require clientcert" for the server.
115 ssl ciphers = ???
116 This variable defines the ciphers that should be offered during SSL
117 negotiation. You should not set this variable unless you know what you do.
118 ssl version = ssl2or3
119 This enumeration variable defines the versions of the SSL protocol that
120 will be used. "ssl2or3" allows dynamic negotiation of SSL v2 or v3, "ssl2"
121 results SSL v2, "ssl3" results in SSL v3 and "tls1" results in TLS v1. TLS
122 (Transport Layer Security) is the (proposed?) new standard for SSL. The
123 default value is "ssl2or3".
124 ssl compatibility = no
125 This variable defines whether SSLeay should be configured for bug
126 compatibility with other SSL implementations. This is probably not
127 desirable because currently no clients with SSL implementations other than
128 SSLeay exist.
129 ssl entropy file =
130 Specifies a file from which processes will read "random bytes" on startup.
131 In order to seed the internal pseudo random number generator, entropy
132 must be provided. On system with a /dev/urandom device file, the processes
133 will retrieve its entropy from the kernel. On systems without kernel
134 entropy support, a file can be supplied that will be read on startup
135 and that will be used to seed the PRNG.
136 ssl entropy bytes = 256
137 Number of bytes that will be read from entropy file. If -1 is given, the
138 complete file will be read.
139 ssl egd socket =
140 Location of the communiation socket of an EGD or PRNGD daemon, from which
141 entropy can be retrieved. This option can be used instead of or together
142 with the "ssl entropy file" directive. 255bytes of entropy will be
143 retrieved from the daemon.
146 Running samba with OpenSSL
147 ==========================
148 Samba is started as usual. The daemon will ask for the private key's pass
149 phrase before it goes to background if the private key has been encrypted.
150 If you start smbd from inetd, this won't work. Therefore you must not encrypt
151 your private key if you run smbd from inetd.
153 Windows clients will try to connect to the SSL enabled samba daemon and they
154 will fail. This can fill your log with failed SSL negotiation messages. To
155 avoid this, you can either not run nmbd (if all clients use DNS to look up
156 the server), which will leave the Windows machine unaware of the server, or
157 list all (local) Windows machines in the "ssl hosts resign" variable.
160 About certificates
161 ==================
162 Secure samba servers will not be set up for public use as it is the case with
163 secure web servers. Most installations will probably use it for distributed
164 offices that use parts of the internet for their intranet, for access to a
165 web server that's physically hosted by the provider or simply for teleworking.
166 All these applications work with a known group of users that can easily agree
167 on a certification authority. The CA can be operated by the company and the
168 policy for issuing certificates can be determined by the company. If samba is
169 configured to verify client certificates, it (currently) only verifies
170 whether a valid certificate exists. It does not verify any of the data within
171 the certificate (although it prints some of the data to the log file).
174 Which clients are available that support SSL?
175 =============================================
176 Currently there are only smbclient which is part of the samba package and
177 Sharity. Shariy versions newer than 0.14 in the beta branch and 1.01 in the
178 main branch can be compiled with SSLeay. Sharity is a CIFS/SMB client
179 implementation for Unix. It is a commercial product, but it is available in
180 source code and the demo-mode allows access to the first three layers of the
181 mounted directory hierarchy. Licenses for universities and students are free.
182 Sharity is available at
184 http://www.obdev.at/Products/Sharity.html
188 ###########################################################################
189 Basics about Cryptography and SSL(eay)
190 ###########################################################################
192 There are many good introductions to cryptography. I assume that the reader
193 is familiar with the words "encryption", "digital signature" and RSA. If you
194 don't know these terms, please read the cryptography FAQ part 6 and 7, which
195 is posted to the usenet newsgroup sci.crypt. It is also available from
197 ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq
198 and
199 http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq
201 I'll concentrate on the questions specific to SSL and samba here.
204 What is a certificate?
205 ======================
206 A certificate is issued by an issuer, usually a "Certification Authority"
207 (CA), who confirms something by issuing the certificate. The subject of this
208 confirmation depends on the CA's policy. CAs for secure web servers (used for
209 shopping malls etc.) usually only attest that the given public key belongs the
210 the given domain name. Company-wide CAs might attest that you are an employee
211 of the company, that you have permissions to use a server or whatever.
214 What is an X.509 certificate technically?
215 =========================================
216 Technically, the certificate is a block of data signed by the certificate
217 issuer (the CA). The relevant fields are:
218 - unique identifier (name) of the certificate issuer
219 - time range during that the certificate is valid
220 - unique identifier (name) of the certified subject
221 - public key of the certified subject
222 - the issuer's signature over all of the above
223 If this certificate should be verified, the verifier must have a table of the
224 names and public keys of trusted CAs. For simplicity, these tables are lists
225 of certificates issued by the respective CAs for themselves (self-signed
226 certificates).
229 What are the implications of this certificate structure?
230 ========================================================
231 - Because the certificate contains the subject's public key, the
232 certificate and the private key together are all that's needed to encrypt
233 and decrypt.
234 - To verify certificates, you need the certificates of all CAs you trust.
235 - The simplest form of a dummy-certificate is one that's signed by the
236 subject itself.
237 - A CA is needed. The client can't simply issue local certificates for
238 servers it trusts because the server determines which certificate it
239 presents.
243 ###########################################################################
244 Setting up files and directories for OpenSSL
245 ###########################################################################
247 The first thing you should do is to change your PATH environment variable to
248 include the bin directory of OpenSSL. E.g.:
250 PATH=$PATH:/usr/local/ssl/bin
252 If your system's kernel supports a /dev/urandom device, all OpenSSL operations
253 will automatically retrieve its entropy from it. If your system does not
254 support /dev/urandom, you may install an EGD/PRNGD daemon for entropy
255 supply or can generate seed from reading files (that should contain information
256 unpredictable/unknown to attackers). Use the "-rand" option to the openssl
257 commands to specify the entropy source (if /dev/urandom is not available).
259 OpenSSL additionally keeps random seed in the $HOME/.rnd file. You can
260 initialize this file using:
262 openssl rand -rand /tmp/rfile.txt > $HOME/.rnd
263 rm -f /tmp/rfile.txt # nobody must know!!
265 or
267 openssl rand -rand /path/to/egd-socket > $HOME/.rnd
269 How to create a keypair
270 =======================
271 This is done with 'genrsa' for RSA keys and 'gendsa' for DSA keys. For an RSA
272 key with 1024 bits which is written to the file "key.pem" type:
274 openssl genrsa -des3 -rand /path/to/source 1024 > key.pem
276 You will be asked for a pass phrase to protect this key. If you don't want to
277 protect your private key with a pass phrase, just omit the parameter "-des3".
278 If you want a different key size, replace the parameter "1024". You really
279 should use a pass phrase.
281 If you want to remove the pass phrase from a key use:
283 openssl rsa -in key.pem -out newkey.pem
285 And to add or change a pass phrase:
287 openssl rsa -des3 -in key.pem -out newkey.pem
290 How to create a dummy certificate
291 =================================
292 If you still have your keypair in the file "key.pem", the command
294 openssl req -new -x509 -key key.pem -out cert.pem
296 will write a self-signed dummy certificate to the file "cert.pem". This can
297 be used for testing or if only encryption and no certification is needed.
298 Please bear in mind that encryption without authentication (certification)
299 can never be secure. It's open to (at least) "man-in-the-middle" attacks.
302 How to create a certificate signing request
303 ===========================================
304 You must not simply send your keypair to the CA for signing because it
305 contains the private key which _must_ be kept secret. A signing request
306 consists of your public key and some additional information you want to have
307 bound to that key by the certificate. If you operate a secure web server,
308 this additional information will (among other things) contain the URL of
309 your server in the field "Common Name". The certificate signing request is
310 created from the keypair with the following command (assuming that the key
311 pair is still in "key.pem"):
313 openssl req -new -key key.pem -out csr.pem
315 This command will ask you for the information which must be included in the
316 certificate and will write the signing request to the file "csr.pem". This
317 signing request is all the CA needs for signing, at least technically. Most
318 CAs will demand bureaucratic material and money, too.
321 How to set up a Certification Authority (CA)
322 ============================================
323 Being a certification authority requires a database that holds the CA's
324 keypair, the CA's certificate, a list of all signed certificates and other
325 information. This database is kept in a directory hierarchy below a
326 configurable starting point. The starting point must be configured in the
327 ssleay.conf file. This file is at /usr/local/ssl/lib/ssleay.conf if you have
328 not changed the default installation path.
330 The first thing you should do is to edit this file according to your needs.
331 Let's assume that you want to hold the CA's database at the directory
332 "/usr/local/ssl/CA". Change the variable "dir" in section "CA_default" to
333 this path. You may also want to edit the default settings for some variables,
334 but the values given should be OK. This path is also contained in the shell
335 script CA.sh, which should be at "/usr/local/ssl/bin/CA.sh". Change the path
336 in the shell script:
338 CATOP=/usr/local/ssl/CA
339 CAKEY=./cakey.pem # relative to $CATOP/
340 CACERT=./cacert.pem # relative to $CATOP/private/
342 Then create the directory "/usr/local/ssl/CA" and make it writable for the
343 user that operates the CA. You should also initialize SSLeay as CA user (set
344 up the random number generator). Now you should call the shell script CA.sh
345 to set up the initial database:
347 CA.sh -newca
349 This command will ask you whether you want to use an existing certificate or
350 create one. Just press enter to create a new key pair and certificate. You
351 will be asked the usual questions for certificates: the country, state, city,
352 "Common Name", etc. Enter the appropriate values for the CA. When CA.sh
353 finishes, it has set up a bunch of directories and files. A CA must publish
354 it's certificate, which is in the file "/usr/local/ssl/CA/cacert.pem".
357 How to sign a certificate request
358 =================================
359 After setting up the CA stuff, you can start signing certificate requests.
360 Make sure that the SSLeay utilities know where the configuration file is.
361 The default is compiled in, if you don't use the default location, add the
362 parameter "-config <cfg-file>". Make also sure that the configuration file
363 contains the correct path to the CA database. If all this is set up properly,
364 you can sign the request in the file "csr.pem" with the command:
366 openssl ca -policy policy_anything -days 365 -infiles csr.pem >cert.pem
368 The resulting certificate (and additional information) will be in "cert.pem".
369 If you want the certificate to be valid for a period different from 365 days,
370 simply change the "-days" parameter.
373 How to install a new CA certificate
374 ===================================
375 Whereever a certificate must be checked, the CA's certificate must be
376 available. Let's take the common case where the client verifies the server's
377 certificate. The case where the server verfies the client's certificate works
378 the same way. The client receives the server's certificate, which contains
379 the "Distinguished Name" of the CA. To verify whether the signature in this
380 certificate is OK, it must look up the public key of that CA. Therefore each
381 client must hold a database of CAs, indexed by CA name. This database is best
382 kept in a directory where each file contains the certificate of one CA and is
383 named after the hashvalue (checksum) of the CA's name. This section describes
384 how such a database is managed technically. Whether or not to install (and
385 thereby trust) a CA is a totally different matter.
387 The client must know the directory of the CA database. This can be configured.
388 There may also be a configuration option to set up a CA database file which
389 contains all CA certs in one file. Let's assume that the CA database is kept
390 in the directory "/usr/local/ssl/certs". The following example assumes that
391 the CA's certificate is in the file "cacert.pem" and the CA is known as
392 "myCA". To install the certificate, do the following:
394 cp cacert.pem /usr/local/ssl/cers/myCA.pem
395 cd /usr/local/ssl/certs
396 ln -s myCA.pem `openssl x509 -noout -hash < myCA.pem`.0
398 The last command creates a link from the hashed name to the real file.
400 From now on all certificates signed by the myCA authority will be accepted by
401 clients that use the directory "/usr/local/ssl/certs/" as their CA certificate
402 database.