2 !== SSLeay.txt for Samba release 2.0.0-beta1 13 Nov 1998
4 Contributor: Christian Starkjohann <cs@obdev.at>
8 Subject: Compiling and using samba with SSL support
9 ============================================================================
11 What is SSL and SSLeay?
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
17 SSLeay is a free implementation of the SSL protocol. It is available from
19 ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/
21 The current version while these lines are written is 0.9.0. Encryption is
22 plagued by legal problems of all kinds. For a discussion of these please
23 read the documentation of SSLeay, which is available at
25 http://www.psy.uq.edu.au/~ftp/Crypto/
27 To compile samba with SSL support, you must first compile and install SSLeay.
28 SSLeay consists of a library (which can be linked to other applications like
29 samba) and several utility programs needed for key generation, certification
30 etc. SSLeay installs to /usr/local/ssl/ by default.
33 Compiling samba with SSLeay
34 ===========================
35 1. Get and install SSLeay. The rest of this documentation assumes that you
36 have installed it at the default location, which is /usr/local/ssl/.
37 I have used SSLeay 0.9.0, but samba will probably also work with other
38 versions (but not with versions older than 0.6).
39 2. Modify the Makefile. At the end of the configurable section you can find
40 the SSL definitions. You can find them quickly by searching for SSL_ROOT.
41 Unremark the definitions and modify SSL_ROOT if necessary.
42 3. Compile and install as usual.
45 Configuring SSL in samba
46 ========================
47 Before you configure SSL, you should know the basics of cryptography and how
48 SSL relates to all of this. A basic introduction can be found further down in
49 this document. The following variables in the "[global]" section of the
50 configuration file are used to configure SSL:
53 This variable enables or disables the entire SSL mode. If it is set to
54 "no", the SSL enabled samba behaves exactly like the non-SSL samba. If set
55 to "yes", it depends on the variables "ssl hosts" and "ssl hosts resign"
56 whether an SSL connection will be required.
58 ssl hosts resign = 192.168.
59 These two variables define whether samba will go into SSL mode or not. If
60 none of them is defined, samba will allow only SSL connections. If the
61 "ssl hosts" variable lists hosts (by IP-address, IP-address range, net
62 group or name), only these hosts will be forced into SSL mode. If the
63 "ssl hosts resign" variable lists hosts, only these hosts will NOT be
64 forced into SSL mode. The syntax for these two variables is the same as
65 for the "hosts allow" and "hosts deny" pair of variables, only that the
66 subject of the decision is different: It's not the access right but
67 whether SSL is used or not. See the man page of smb.conf (section about
68 "allow hosts") for details. The above example requires SSL connections
69 from all hosts outside the local net (which is 192.168.*.*).
70 ssl CA certDir = /usr/local/ssl/certs
71 This variable defines where to look up the Certification Autorities. The
72 given directory should contain one file for each CA that samba will trust.
73 The file name must be the hash value over the "Distinguished Name" of the
74 CA. How this directory is set up is explained later in this document. All
75 files within the directory that don't fit into this naming scheme are
76 ignored. You don't need this variable if you don't verify client
78 ssl CA certFile = /usr/local/ssl/certs/trustedCAs.pem
79 This variable is a second way to define the trusted CAs. The certificates
80 of the trusted CAs are collected in one big file and this variable points
81 to the file. You will probably only use one of the two ways to define your
82 CAs. The first choice is preferable if you have many CAs or want to be
83 flexible, the second is perferable if you only have one CA and want to
84 keep things simple (you won't need to create the hashed file names). You
85 don't need this variable if you don't verify client certificates.
86 ssl server cert = /usr/local/ssl/certs/samba.pem
87 This is the file containing the server's certificate. The server _must_
88 have a certificate. The file may also contain the server's private key.
89 See later for how certificates and private keys are created.
90 ssl server key = /usr/local/ssl/private/samba.pem
91 This file contains the private key of the server. If this variable is not
92 defined, the key is looked up in the certificate file (it may be appended
93 to the certificate). The server _must_ have a private key and the
94 certificate _must_ match this private key.
95 ssl client cert = /usr/local/ssl/certs/smbclient.pem
96 The certificate in this file is used by smbclient if it exists. It's needed
97 if the server requires a client certificate.
98 ssl client key = /usr/local/ssl/private/smbclient.pem
99 This is the private key for smbclient. It's only needed if the client
100 should have a certificate.
101 ssl require clientcert = yes
102 If this variable is set to "yes", the server will not tolerate connections
103 from clients that don't have a valid certificate. The directory/file
104 given in "ssl CA certDir" and "ssl CA certFile" will be used to look up
105 the CAs that issued the client's certificate. If the certificate can't be
106 verified positively, the connection will be terminated.
107 If this variable is set to "no", clients don't need certificates. Contrary
108 to web applications you really _should_ require client certificates. In
109 the web environment the client's data is sensitive (credit card numbers)
110 and the server must prove to be trustworthy. In a file server environment
111 the server's data will be sensitive and the clients must prove to be
113 ssl require servercert = yes
114 If this variable is set to "yes", the smbclient will request a certificate
115 from the server. Same as "ssl require clientcert" for the server.
117 This variable defines the ciphers that should be offered during SSL
118 negotiation. You should not set this variable unless you know what you do.
119 ssl version = ssl2or3
120 This enumeration variable defines the versions of the SSL protocol that
121 will be used. "ssl2or3" allows dynamic negotiation of SSL v2 or v3, "ssl2"
122 results SSL v2, "ssl3" results in SSL v3 and "tls1" results in TLS v1. TLS
123 (Transport Layer Security) is the (proposed?) new standard for SSL. The
124 default value is "ssl2or3".
125 ssl compatibility = no
126 This variable defines whether SSLeay should be configured for bug
127 compatibility with other SSL implementations. This is probably not
128 desirable because currently no clients with SSL implementations other than
132 Running samba with SSLeay
133 =========================
134 Samba is started as usual. The daemon will ask for the private key's pass
135 phrase before it goes to background if the private key has been encrypted.
136 If you start smbd from inetd, this won't work. Therefore you must not encrypt
137 your private key if you run smbd from inetd.
139 Windows clients will try to connect to the SSL enabled samba daemon and they
140 will fail. This can fill your log with failed SSL negotiation messages. To
141 avoid this, you can either not run nmbd (if all clients use DNS to look up
142 the server), which will leave the Windows machine unaware of the server, or
143 list all (local) Windows machines in the "ssl hosts resign" variable.
148 Secure samba servers will not be set up for public use as it is the case with
149 secure web servers. Most installations will probably use it for distributed
150 offices that use parts of the internet for their intranet, for access to a
151 web server that's physically hosted by the provider or simply for teleworking.
152 All these applications work with a known group of users that can easily agree
153 on a certification authority. The CA can be operated by the company and the
154 policy for issuing certificates can be determined by the company. If samba is
155 configured to verify client certificates, it (currently) only verifies
156 whether a valid certificate exists. It does not verify any of the data within
157 the certificate (although it prints some of the data to the log file).
160 Which clients are available that support SSL?
161 =============================================
162 Currently there are only smbclient which is part of the samba package and
163 Sharity. Shariy versions newer than 0.14 in the beta branch and 1.01 in the
164 main branch can be compiled with SSLeay. Sharity is a CIFS/SMB client
165 implementation for Unix. It is a commercial product, but it is available in
166 source code and the demo-mode allows access to the first three layers of the
167 mounted directory hierarchy. Licenses for universities and students are free.
168 Sharity is available at
170 http://www.obdev.at/Products/Sharity.html
174 ###########################################################################
175 Basics about Cryptography and SSL(eay)
176 ###########################################################################
178 There are many good introductions to cryptography. I assume that the reader
179 is familiar with the words "encryption", "digital signature" and RSA. If you
180 don't know these terms, please read the cryptography FAQ part 6 and 7, which
181 is posted to the usenet newsgroup sci.crypt. It is also available from
183 ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq
185 http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq
187 I'll concentrate on the questions specific to SSL and samba here.
190 What is a certificate?
191 ======================
192 A certificate is issued by an issuer, usually a "Certification Authority"
193 (CA), who confirms something by issuing the certificate. The subject of this
194 confirmation depends on the CA's policy. CAs for secure web servers (used for
195 shopping malls etc.) usually only attest that the given public key belongs the
196 the given domain name. Company-wide CAs might attest that you are an employee
197 of the company, that you have permissions to use a server or whatever.
200 What is an X.509 certificate technically?
201 =========================================
202 Technically, the certificate is a block of data signed by the certificate
203 issuer (the CA). The relevant fields are:
204 - unique identifier (name) of the certificate issuer
205 - time range during that the certificate is valid
206 - unique identifier (name) of the certified subject
207 - public key of the certified subject
208 - the issuer's signature over all of the above
209 If this certificate should be verified, the verifier must have a table of the
210 names and public keys of trusted CAs. For simplicity, these tables are lists
211 of certificates issued by the respective CAs for themselves (self-signed
215 What are the implications of this certificate structure?
216 ========================================================
217 - Because the certificate contains the subject's public key, the
218 certificate and the private key together are all that's needed to encrypt
220 - To verify certificates, you need the certificates of all CAs you trust.
221 - The simplest form of a dummy-certificate is one that's signed by the
223 - A CA is needed. The client can't simply issue local certificates for
224 servers it trusts because the server determines which certificate it
229 ###########################################################################
230 Setting up files and directories for SSLeay
231 ###########################################################################
233 The first thing you should do is to change your PATH environment variable to
234 include the bin directory of SSLeay. E.g.:
236 PATH=$PATH:/usr/local/ssl/bin
238 Then you should set up SSLeay's random number generator. The state of this
239 random number generator is held in the file ".rnd" in your home directory. To
240 set a reasonable random seed, you need random data. Create a random file with
244 Then type random keys on your keyboard for about one minute. Then type the
245 EOF character (^D) to terminate input. You may also use your favorite editor
246 to create the random file, of course. Now you can create a dummy key to
247 initialize the random number generator:
249 ssleay genrsa -rand /tmp/rfile.txt > /dev/null
252 Don't forget to delete the file /tmp/rfile.txt. It's more or less equivalent
256 How to create a keypair
257 =======================
258 This is done with 'genrsa' for RSA keys and 'gendsa' for DSA keys. For an RSA
259 key with 512 bits which is written to the file "key.pem" type:
261 ssleay genrsa -des3 512 > key.pem
263 You will be asked for a pass phrase to protect this key. If you don't want to
264 protect your private key with a pass phrase, just omit the parameter "-des3".
265 If you want a different key size, replace the parameter "512". You really
266 should use a pass phrase.
268 If you want to remove the pass phrase from a key use:
270 ssleay rsa -in key.pem -out newkey.pem
272 And to add or change a pass phrase:
274 ssleay rsa -des3 -in key.pem -out newkey.pem
277 How to create a dummy certificate
278 =================================
279 If you still have your keypair in the file "key.pem", the command
281 ssleay req -new -x509 -key key.pem -out cert.pem
283 will write a self-signed dummy certificate to the file "cert.pem". This can
284 be used for testing or if only encryption and no certification is needed.
285 Please bear in mind that encryption without authentication (certification)
286 can never be secure. It's open to (at least) "man-in-the-middle" attacks.
289 How to create a certificate signing request
290 ===========================================
291 You must not simply send your keypair to the CA for signing because it
292 contains the private key which _must_ be kept secret. A signing request
293 consists of your public key and some additional information you want to have
294 bound to that key by the certificate. If you operate a secure web server,
295 this additional information will (among other things) contain the URL of
296 your server in the field "Common Name". The certificate signing request is
297 created from the keypair with the following command (assuming that the key
298 pair is still in "key.pem"):
300 ssleay req -new -key key.pem -out csr.pem
302 This command will ask you for the information which must be included in the
303 certificate and will write the signing request to the file "csr.pem". This
304 signing request is all the CA needs for signing, at least technically. Most
305 CAs will demand bureaucratic material and money, too.
308 How to set up a Certification Authority (CA)
309 ============================================
310 Being a certification authority requires a database that holds the CA's
311 keypair, the CA's certificate, a list of all signed certificates and other
312 information. This database is kept in a directory hierarchy below a
313 configurable starting point. The starting point must be configured in the
314 ssleay.conf file. This file is at /usr/local/ssl/lib/ssleay.conf if you have
315 not changed the default installation path.
317 The first thing you should do is to edit this file according to your needs.
318 Let's assume that you want to hold the CA's database at the directory
319 "/usr/local/ssl/CA". Change the variable "dir" in section "CA_default" to
320 this path. You may also want to edit the default settings for some variables,
321 but the values given should be OK. This path is also contained in the shell
322 script CA.sh, which should be at "/usr/local/ssl/bin/CA.sh". Change the path
325 CATOP=/usr/local/ssl/CA
326 CAKEY=./cakey.pem # relative to $CATOP/
327 CACERT=./cacert.pem # relative to $CATOP/private/
329 Then create the directory "/usr/local/ssl/CA" and make it writable for the
330 user that operates the CA. You should also initialize SSLeay as CA user (set
331 up the random number generator). Now you should call the shell script CA.sh
332 to set up the initial database:
336 This command will ask you whether you want to use an existing certificate or
337 create one. Just press enter to create a new key pair and certificate. You
338 will be asked the usual questions for certificates: the country, state, city,
339 "Common Name", etc. Enter the appropriate values for the CA. When CA.sh
340 finishes, it has set up a bunch of directories and files. A CA must publish
341 it's certificate, which is in the file "/usr/local/ssl/CA/cacert.pem".
344 How to sign a certificate request
345 =================================
346 After setting up the CA stuff, you can start signing certificate requests.
347 Make sure that the SSLeay utilities know where the configuration file is.
348 The default is compiled in, if you don't use the default location, add the
349 parameter "-config <cfg-file>". Make also sure that the configuration file
350 contains the correct path to the CA database. If all this is set up properly,
351 you can sign the request in the file "csr.pem" with the command:
353 ssleay ca -policy policy_anything -days 365 -infiles csr.pem >cert.pem
355 The resulting certificate (and additional information) will be in "cert.pem".
356 If you want the certificate to be valid for a period different from 365 days,
357 simply change the "-days" parameter.
360 How to install a new CA certificate
361 ===================================
362 Whereever a certificate must be checked, the CA's certificate must be
363 available. Let's take the common case where the client verifies the server's
364 certificate. The case where the server verfies the client's certificate works
365 the same way. The client receives the server's certificate, which contains
366 the "Distinguished Name" of the CA. To verify whether the signature in this
367 certificate is OK, it must look up the public key of that CA. Therefore each
368 client must hold a database of CAs, indexed by CA name. This database is best
369 kept in a directory where each file contains the certificate of one CA and is
370 named after the hashvalue (checksum) of the CA's name. This section describes
371 how such a database is managed technically. Whether or not to install (and
372 thereby trust) a CA is a totally different matter.
374 The client must know the directory of the CA database. This can be configured.
375 There may also be a configuration option to set up a CA database file which
376 contains all CA certs in one file. Let's assume that the CA database is kept
377 in the directory "/usr/local/ssl/certs". The following example assumes that
378 the CA's certificate is in the file "cacert.pem" and the CA is known as
379 "myCA". To install the certificate, do the following:
381 cp cacert.pem /usr/local/ssl/cers/myCA.pem
382 cd /usr/local/ssl/certs
383 ln -s myCA.pem `ssleay x509 -noout -hash < myCA.pem`.0
385 The last command creates a link from the hashed name to the real file.
387 From now on all certificates signed by the myCA authority will be accepted by
388 clients that use the directory "/usr/local/ssl/certs/" as their CA certificate
git.samba.org / samba.git / blob