1!== 2!== SSLeay.txt for Samba release 2.0.10 23 Jun 2001 3!== 4Contributor: Christian Starkjohann <cs@obdev.at> 5Date: May 29, 1998 6Status: 7 8Subject: Compiling and using samba with SSL support 9============================================================================ 10 11What is SSL and SSLeay? 12======================= 13SSL (Secure Socket Layer) is a protocol for encrypted and authenticated data 14transport. It is used by secure web servers for shopping malls, telebanking 15and things like that. 16 17SSLeay is a free implementation of the SSL protocol. It is available from 18 19 ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/ 20 21The current version while these lines are written is 0.9.0. Encryption is 22plagued by legal problems of all kinds. For a discussion of these please 23read the documentation of SSLeay, which is available at 24 25 http://www.psy.uq.edu.au/~ftp/Crypto/ 26 27To compile samba with SSL support, you must first compile and install SSLeay. 28SSLeay consists of a library (which can be linked to other applications like 29samba) and several utility programs needed for key generation, certification 30etc. SSLeay installs to /usr/local/ssl/ by default. 31 32 33Compiling samba with SSLeay 34=========================== 351. 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). 392. 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. 423. Compile and install as usual. 43 44 45Configuring SSL in samba 46======================== 47Before you configure SSL, you should know the basics of cryptography and how 48SSL relates to all of this. A basic introduction can be found further down in 49this document. The following variables in the "[global]" section of the 50configuration file are used to configure SSL: 51 52ssl = yes 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. 57ssl hosts = 58ssl 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.*.*). 70ssl 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 77 certificates. 78ssl 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. 86ssl 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. 90ssl 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. 95ssl 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. 98ssl 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. 101ssl 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 112 trustworthy. 113ssl 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. 116ssl ciphers = ??? 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. 119ssl 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". 125ssl 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 129 SSLeay exist. 130 131 132Running samba with SSLeay 133========================= 134Samba is started as usual. The daemon will ask for the private key's pass 135phrase before it goes to background if the private key has been encrypted. 136If you start smbd from inetd, this won't work. Therefore you must not encrypt 137your private key if you run smbd from inetd. 138 139Windows clients will try to connect to the SSL enabled samba daemon and they 140will fail. This can fill your log with failed SSL negotiation messages. To 141avoid this, you can either not run nmbd (if all clients use DNS to look up 142the server), which will leave the Windows machine unaware of the server, or 143list all (local) Windows machines in the "ssl hosts resign" variable. 144 145 146About certificates 147================== 148Secure samba servers will not be set up for public use as it is the case with 149secure web servers. Most installations will probably use it for distributed 150offices that use parts of the internet for their intranet, for access to a 151web server that's physically hosted by the provider or simply for teleworking. 152All these applications work with a known group of users that can easily agree 153on a certification authority. The CA can be operated by the company and the 154policy for issuing certificates can be determined by the company. If samba is 155configured to verify client certificates, it (currently) only verifies 156whether a valid certificate exists. It does not verify any of the data within 157the certificate (although it prints some of the data to the log file). 158 159 160Which clients are available that support SSL? 161============================================= 162Currently there are only smbclient which is part of the samba package and 163Sharity. Shariy versions newer than 0.14 in the beta branch and 1.01 in the 164main branch can be compiled with SSLeay. Sharity is a CIFS/SMB client 165implementation for Unix. It is a commercial product, but it is available in 166source code and the demo-mode allows access to the first three layers of the 167mounted directory hierarchy. Licenses for universities and students are free. 168Sharity is available at 169 170 http://www.obdev.at/Products/Sharity.html 171 172 173 174########################################################################### 175Basics about Cryptography and SSL(eay) 176########################################################################### 177 178There are many good introductions to cryptography. I assume that the reader 179is familiar with the words "encryption", "digital signature" and RSA. If you 180don't know these terms, please read the cryptography FAQ part 6 and 7, which 181is posted to the usenet newsgroup sci.crypt. It is also available from 182 183 ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq 184and 185 http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq 186 187I'll concentrate on the questions specific to SSL and samba here. 188 189 190What is a certificate? 191====================== 192A certificate is issued by an issuer, usually a "Certification Authority" 193(CA), who confirms something by issuing the certificate. The subject of this 194confirmation depends on the CA's policy. CAs for secure web servers (used for 195shopping malls etc.) usually only attest that the given public key belongs the 196the given domain name. Company-wide CAs might attest that you are an employee 197of the company, that you have permissions to use a server or whatever. 198 199 200What is an X.509 certificate technically? 201========================================= 202Technically, the certificate is a block of data signed by the certificate 203issuer (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 209If this certificate should be verified, the verifier must have a table of the 210names and public keys of trusted CAs. For simplicity, these tables are lists 211of certificates issued by the respective CAs for themselves (self-signed 212certificates). 213 214 215What 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 219 and decrypt. 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 222 subject itself. 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 225 presents. 226 227 228 229########################################################################### 230Setting up files and directories for SSLeay 231########################################################################### 232 233The first thing you should do is to change your PATH environment variable to 234include the bin directory of SSLeay. E.g.: 235 236 PATH=$PATH:/usr/local/ssl/bin 237 238Then you should set up SSLeay's random number generator. The state of this 239random number generator is held in the file ".rnd" in your home directory. To 240set a reasonable random seed, you need random data. Create a random file with 241 242 cat >/tmp/rfile.txt 243 244Then type random keys on your keyboard for about one minute. Then type the 245EOF character (^D) to terminate input. You may also use your favorite editor 246to create the random file, of course. Now you can create a dummy key to 247initialize the random number generator: 248 249 ssleay genrsa -rand /tmp/rfile.txt > /dev/null 250 rm -f /tmp/rfile.txt 251 252Don't forget to delete the file /tmp/rfile.txt. It's more or less equivalent 253to your private key! 254 255 256How to create a keypair 257======================= 258This is done with 'genrsa' for RSA keys and 'gendsa' for DSA keys. For an RSA 259key with 512 bits which is written to the file "key.pem" type: 260 261 ssleay genrsa -des3 512 > key.pem 262 263You will be asked for a pass phrase to protect this key. If you don't want to 264protect your private key with a pass phrase, just omit the parameter "-des3". 265If you want a different key size, replace the parameter "512". You really 266should use a pass phrase. 267 268If you want to remove the pass phrase from a key use: 269 270 ssleay rsa -in key.pem -out newkey.pem 271 272And to add or change a pass phrase: 273 274 ssleay rsa -des3 -in key.pem -out newkey.pem 275 276 277How to create a dummy certificate 278================================= 279If you still have your keypair in the file "key.pem", the command 280 281 ssleay req -new -x509 -key key.pem -out cert.pem 282 283will write a self-signed dummy certificate to the file "cert.pem". This can 284be used for testing or if only encryption and no certification is needed. 285Please bear in mind that encryption without authentication (certification) 286can never be secure. It's open to (at least) "man-in-the-middle" attacks. 287 288 289How to create a certificate signing request 290=========================================== 291You must not simply send your keypair to the CA for signing because it 292contains the private key which _must_ be kept secret. A signing request 293consists of your public key and some additional information you want to have 294bound to that key by the certificate. If you operate a secure web server, 295this additional information will (among other things) contain the URL of 296your server in the field "Common Name". The certificate signing request is 297created from the keypair with the following command (assuming that the key 298pair is still in "key.pem"): 299 300 ssleay req -new -key key.pem -out csr.pem 301 302This command will ask you for the information which must be included in the 303certificate and will write the signing request to the file "csr.pem". This 304signing request is all the CA needs for signing, at least technically. Most 305CAs will demand bureaucratic material and money, too. 306 307 308How to set up a Certification Authority (CA) 309============================================ 310Being a certification authority requires a database that holds the CA's 311keypair, the CA's certificate, a list of all signed certificates and other 312information. This database is kept in a directory hierarchy below a 313configurable starting point. The starting point must be configured in the 314ssleay.conf file. This file is at /usr/local/ssl/lib/ssleay.conf if you have 315not changed the default installation path. 316 317The first thing you should do is to edit this file according to your needs. 318Let'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 320this path. You may also want to edit the default settings for some variables, 321but the values given should be OK. This path is also contained in the shell 322script CA.sh, which should be at "/usr/local/ssl/bin/CA.sh". Change the path 323in the shell script: 324 325 CATOP=/usr/local/ssl/CA 326 CAKEY=./cakey.pem # relative to $CATOP/ 327 CACERT=./cacert.pem # relative to $CATOP/private/ 328 329Then create the directory "/usr/local/ssl/CA" and make it writable for the 330user that operates the CA. You should also initialize SSLeay as CA user (set 331up the random number generator). Now you should call the shell script CA.sh 332to set up the initial database: 333 334 CA.sh -newca 335 336This command will ask you whether you want to use an existing certificate or 337create one. Just press enter to create a new key pair and certificate. You 338will 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 340finishes, it has set up a bunch of directories and files. A CA must publish 341it's certificate, which is in the file "/usr/local/ssl/CA/cacert.pem". 342 343 344How to sign a certificate request 345================================= 346After setting up the CA stuff, you can start signing certificate requests. 347Make sure that the SSLeay utilities know where the configuration file is. 348The default is compiled in, if you don't use the default location, add the 349parameter "-config <cfg-file>". Make also sure that the configuration file 350contains the correct path to the CA database. If all this is set up properly, 351you can sign the request in the file "csr.pem" with the command: 352 353 ssleay ca -policy policy_anything -days 365 -infiles csr.pem >cert.pem 354 355The resulting certificate (and additional information) will be in "cert.pem". 356If you want the certificate to be valid for a period different from 365 days, 357simply change the "-days" parameter. 358 359 360How to install a new CA certificate 361=================================== 362Whereever a certificate must be checked, the CA's certificate must be 363available. Let's take the common case where the client verifies the server's 364certificate. The case where the server verfies the client's certificate works 365the same way. The client receives the server's certificate, which contains 366the "Distinguished Name" of the CA. To verify whether the signature in this 367certificate is OK, it must look up the public key of that CA. Therefore each 368client must hold a database of CAs, indexed by CA name. This database is best 369kept in a directory where each file contains the certificate of one CA and is 370named after the hashvalue (checksum) of the CA's name. This section describes 371how such a database is managed technically. Whether or not to install (and 372thereby trust) a CA is a totally different matter. 373 374The client must know the directory of the CA database. This can be configured. 375There may also be a configuration option to set up a CA database file which 376contains all CA certs in one file. Let's assume that the CA database is kept 377in the directory "/usr/local/ssl/certs". The following example assumes that 378the CA's certificate is in the file "cacert.pem" and the CA is known as 379"myCA". To install the certificate, do the following: 380 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 384 385The last command creates a link from the hashed name to the real file. 386 387From now on all certificates signed by the myCA authority will be accepted by 388clients that use the directory "/usr/local/ssl/certs/" as their CA certificate 389database. 390 391 392 393