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