diff options
Diffstat (limited to 'docs/textdocs/Samba-OpenSSL.txt')
| -rw-r--r-- | docs/textdocs/Samba-OpenSSL.txt | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/docs/textdocs/Samba-OpenSSL.txt b/docs/textdocs/Samba-OpenSSL.txt new file mode 100644 index 0000000000..e1b54b1a03 --- /dev/null +++ b/docs/textdocs/Samba-OpenSSL.txt @@ -0,0 +1,405 @@ +Contributor: Christian Starkjohann <cs@obdev.at> +Date: May 29, 1998 +Status: + +Comment: Updated by Lutz Jaenicke <Lutz.Jaenicke@aet.TU-Cottbus.DE> +Date: July 16, 2001 + +Subject: Compiling and using samba with SSL support +============================================================================ + +What is SSL and SSLeay/OpenSSL? +=============================== +SSL (Secure Socket Layer) is a protocol for encrypted and authenticated data +transport. It is used by secure web servers for shopping malls, telebanking +and things like that. + +SSLeay is a free implementation of the SSL protocol. The successor of it is +OpenSSL, available from + + http://www.openssl.org/ + +The current version while these lines are written is 0.9.6b. In some countries +encryption is plagued by legal problems, even though things have relaxed a +lot in the last years. + +To compile samba with SSL support, you must first compile and install OpenSSL. +At least version 0.9.5 of OpenSSL is required. Version 0.9.6b is the latest +version and is strongly recommended. +OpenSSL consists of a library (which can be linked to other applications like +samba) and several utility programs needed for key generation, certification +etc. OpenSSL installs to /usr/local/ssl/ by default. + + +Compiling samba with OpenSSL +============================ +1. Get and install OpenSSL. The rest of this documentation assumes that you + have installed it at the default location, which is /usr/local/ssl/. +2. Call "configure" with the "--with-ssl" flag. If OpenSSL is not installed in + the default directory, you can use the "--with-sslinc" and "--with-ssllib" + flags to specify the location. +3. Compile and install as usual. + + +Configuring SSL in samba +======================== +Before you configure SSL, you should know the basics of cryptography and how +SSL relates to all of this. A basic introduction can be found further down in +this document. The following variables in the "[global]" section of the +configuration file are used to configure SSL: + +ssl = yes + This variable enables or disables the entire SSL mode. If it is set to + "no", the SSL enabled samba behaves exactly like the non-SSL samba. If set + to "yes", it depends on the variables "ssl hosts" and "ssl hosts resign" + whether an SSL connection will be required. +ssl hosts = +ssl hosts resign = 192.168. + These two variables define whether samba will go into SSL mode or not. If + none of them is defined, samba will allow only SSL connections. If the + "ssl hosts" variable lists hosts (by IP-address, IP-address range, net + group or name), only these hosts will be forced into SSL mode. If the + "ssl hosts resign" variable lists hosts, only these hosts will NOT be + forced into SSL mode. The syntax for these two variables is the same as + for the "hosts allow" and "hosts deny" pair of variables, only that the + subject of the decision is different: It's not the access right but + whether SSL is used or not. See the man page of smb.conf (section about + "allow hosts") for details. The above example requires SSL connections + from all hosts outside the local net (which is 192.168.*.*). +ssl CA certDir = /usr/local/ssl/certs + This variable defines where to look up the Certification Autorities. The + given directory should contain one file for each CA that samba will trust. + The file name must be the hash value over the "Distinguished Name" of the + CA. How this directory is set up is explained later in this document. All + files within the directory that don't fit into this naming scheme are + ignored. You don't need this variable if you don't verify client + certificates. +ssl CA certFile = /usr/local/ssl/certs/trustedCAs.pem + This variable is a second way to define the trusted CAs. The certificates + of the trusted CAs are collected in one big file and this variable points + to the file. You will probably only use one of the two ways to define your + CAs. The first choice is preferable if you have many CAs or want to be + flexible, the second is perferable if you only have one CA and want to + keep things simple (you won't need to create the hashed file names). You + don't need this variable if you don't verify client certificates. +ssl server cert = /usr/local/ssl/certs/samba.pem + This is the file containing the server's certificate. The server _must_ + have a certificate. The file may also contain the server's private key. + See later for how certificates and private keys are created. +ssl server key = /usr/local/ssl/private/samba.pem + This file contains the private key of the server. If this variable is not + defined, the key is looked up in the certificate file (it may be appended + to the certificate). The server _must_ have a private key and the + certificate _must_ match this private key. +ssl client cert = /usr/local/ssl/certs/smbclient.pem + The certificate in this file is used by smbclient if it exists. It's needed + if the server requires a client certificate. +ssl client key = /usr/local/ssl/private/smbclient.pem + This is the private key for smbclient. It's only needed if the client + should have a certificate. +ssl require clientcert = yes + If this variable is set to "yes", the server will not tolerate connections + from clients that don't have a valid certificate. The directory/file + given in "ssl CA certDir" and "ssl CA certFile" will be used to look up + the CAs that issued the client's certificate. If the certificate can't be + verified positively, the connection will be terminated. + If this variable is set to "no", clients don't need certificates. Contrary + to web applications you really _should_ require client certificates. In + the web environment the client's data is sensitive (credit card numbers) + and the server must prove to be trustworthy. In a file server environment + the server's data will be sensitive and the clients must prove to be + trustworthy. +ssl require servercert = yes + If this variable is set to "yes", the smbclient will request a certificate + from the server. Same as "ssl require clientcert" for the server. +ssl ciphers = ??? + This variable defines the ciphers that should be offered during SSL + negotiation. You should not set this variable unless you know what you do. +ssl version = ssl2or3 + This enumeration variable defines the versions of the SSL protocol that + will be used. "ssl2or3" allows dynamic negotiation of SSL v2 or v3, "ssl2" + results SSL v2, "ssl3" results in SSL v3 and "tls1" results in TLS v1. TLS + (Transport Layer Security) is the (proposed?) new standard for SSL. The + default value is "ssl2or3". +ssl compatibility = no + This variable defines whether SSLeay should be configured for bug + compatibility with other SSL implementations. This is probably not + desirable because currently no clients with SSL implementations other than + SSLeay exist. +ssl entropy file = + Specifies a file from which processes will read "random bytes" on startup. + In order to seed the internal pseudo random number generator, entropy + must be provided. On system with a /dev/urandom device file, the processes + will retrieve its entropy from the kernel. On systems without kernel + entropy support, a file can be supplied that will be read on startup + and that will be used to seed the PRNG. +ssl entropy bytes = 256 + Number of bytes that will be read from entropy file. If -1 is given, the + complete file will be read. +ssl egd socket = + Location of the communiation socket of an EGD or PRNGD daemon, from which + entropy can be retrieved. This option can be used instead of or together + with the "ssl entropy file" directive. 255bytes of entropy will be + retrieved from the daemon. + + +Running samba with OpenSSL +========================== +Samba is started as usual. The daemon will ask for the private key's pass +phrase before it goes to background if the private key has been encrypted. +If you start smbd from inetd, this won't work. Therefore you must not encrypt +your private key if you run smbd from inetd. + +Windows clients will try to connect to the SSL enabled samba daemon and they +will fail. This can fill your log with failed SSL negotiation messages. To +avoid this, you can either not run nmbd (if all clients use DNS to look up +the server), which will leave the Windows machine unaware of the server, or +list all (local) Windows machines in the "ssl hosts resign" variable. + + +About certificates +================== +Secure samba servers will not be set up for public use as it is the case with +secure web servers. Most installations will probably use it for distributed +offices that use parts of the internet for their intranet, for access to a +web server that's physically hosted by the provider or simply for teleworking. +All these applications work with a known group of users that can easily agree +on a certification authority. The CA can be operated by the company and the +policy for issuing certificates can be determined by the company. If samba is +configured to verify client certificates, it (currently) only verifies +whether a valid certificate exists. It does not verify any of the data within +the certificate (although it prints some of the data to the log file). + + +Which clients are available that support SSL? +============================================= +Currently there are only smbclient which is part of the samba package and +Sharity. Shariy versions newer than 0.14 in the beta branch and 1.01 in the +main branch can be compiled with SSLeay. Sharity is a CIFS/SMB client +implementation for Unix. It is a commercial product, but it is available in +source code and the demo-mode allows access to the first three layers of the +mounted directory hierarchy. Licenses for universities and students are free. +Sharity is available at + + http://www.obdev.at/Products/Sharity.html + + + +########################################################################### +Basics about Cryptography and SSL(eay) +########################################################################### + +There are many good introductions to cryptography. I assume that the reader +is familiar with the words "encryption", "digital signature" and RSA. If you +don't know these terms, please read the cryptography FAQ part 6 and 7, which +is posted to the usenet newsgroup sci.crypt. It is also available from + + ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq +and + http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq + +I'll concentrate on the questions specific to SSL and samba here. + + +What is a certificate? +====================== +A certificate is issued by an issuer, usually a "Certification Authority" +(CA), who confirms something by issuing the certificate. The subject of this +confirmation depends on the CA's policy. CAs for secure web servers (used for +shopping malls etc.) usually only attest that the given public key belongs the +the given domain name. Company-wide CAs might attest that you are an employee +of the company, that you have permissions to use a server or whatever. + + +What is an X.509 certificate technically? +========================================= +Technically, the certificate is a block of data signed by the certificate +issuer (the CA). The relevant fields are: + - unique identifier (name) of the certificate issuer + - time range during that the certificate is valid + - unique identifier (name) of the certified subject + - public key of the certified subject + - the issuer's signature over all of the above +If this certificate should be verified, the verifier must have a table of the +names and public keys of trusted CAs. For simplicity, these tables are lists +of certificates issued by the respective CAs for themselves (self-signed +certificates). + + +What are the implications of this certificate structure? +======================================================== + - Because the certificate contains the subject's public key, the + certificate and the private key together are all that's needed to encrypt + and decrypt. + - To verify certificates, you need the certificates of all CAs you trust. + - The simplest form of a dummy-certificate is one that's signed by the + subject itself. + - A CA is needed. The client can't simply issue local certificates for + servers it trusts because the server determines which certificate it + presents. + + + +########################################################################### +Setting up files and directories for OpenSSL +########################################################################### + +The first thing you should do is to change your PATH environment variable to +include the bin directory of OpenSSL. E.g.: + + PATH=$PATH:/usr/local/ssl/bin + +If your system's kernel supports a /dev/urandom device, all OpenSSL operations +will automatically retrieve its entropy from it. If your system does not +support /dev/urandom, you may install an EGD/PRNGD daemon for entropy +supply or can generate seed from reading files (that should contain information +unpredictable/unknown to attackers). Use the "-rand" option to the openssl +commands to specify the entropy source (if /dev/urandom is not available). + +OpenSSL additionally keeps random seed in the $HOME/.rnd file. You can +initialize this file using: + + openssl rand -rand /tmp/rfile.txt > $HOME/.rnd + rm -f /tmp/rfile.txt # nobody must know!! + +or + + openssl rand -rand /path/to/egd-socket > $HOME/.rnd + +How to create a keypair +======================= +This is done with 'genrsa' for RSA keys and 'gendsa' for DSA keys. For an RSA +key with 1024 bits which is written to the file "key.pem" type: + + openssl genrsa -des3 -rand /path/to/source 1024 > key.pem + +You will be asked for a pass phrase to protect this key. If you don't want to +protect your private key with a pass phrase, just omit the parameter "-des3". +If you want a different key size, replace the parameter "1024". You really +should use a pass phrase. + +If you want to remove the pass phrase from a key use: + + openssl rsa -in key.pem -out newkey.pem + +And to add or change a pass phrase: + + openssl rsa -des3 -in key.pem -out newkey.pem + + +How to create a dummy certificate +================================= +If you still have your keypair in the file "key.pem", the command + + openssl req -new -x509 -key key.pem -out cert.pem + +will write a self-signed dummy certificate to the file "cert.pem". This can +be used for testing or if only encryption and no certification is needed. +Please bear in mind that encryption without authentication (certification) +can never be secure. It's open to (at least) "man-in-the-middle" attacks. + + +How to create a certificate signing request +=========================================== +You must not simply send your keypair to the CA for signing because it +contains the private key which _must_ be kept secret. A signing request +consists of your public key and some additional information you want to have +bound to that key by the certificate. If you operate a secure web server, +this additional information will (among other things) contain the URL of +your server in the field "Common Name". The certificate signing request is +created from the keypair with the following command (assuming that the key +pair is still in "key.pem"): + + openssl req -new -key key.pem -out csr.pem + +This command will ask you for the information which must be included in the +certificate and will write the signing request to the file "csr.pem". This +signing request is all the CA needs for signing, at least technically. Most +CAs will demand bureaucratic material and money, too. + + +How to set up a Certification Authority (CA) +============================================ +Being a certification authority requires a database that holds the CA's +keypair, the CA's certificate, a list of all signed certificates and other +information. This database is kept in a directory hierarchy below a +configurable starting point. The starting point must be configured in the +ssleay.conf file. This file is at /usr/local/ssl/lib/ssleay.conf if you have +not changed the default installation path. + +The first thing you should do is to edit this file according to your needs. +Let's assume that you want to hold the CA's database at the directory +"/usr/local/ssl/CA". Change the variable "dir" in section "CA_default" to +this path. You may also want to edit the default settings for some variables, +but the values given should be OK. This path is also contained in the shell +script CA.sh, which should be at "/usr/local/ssl/bin/CA.sh". Change the path +in the shell script: + + CATOP=/usr/local/ssl/CA + CAKEY=./cakey.pem # relative to $CATOP/ + CACERT=./cacert.pem # relative to $CATOP/private/ + +Then create the directory "/usr/local/ssl/CA" and make it writable for the +user that operates the CA. You should also initialize SSLeay as CA user (set +up the random number generator). Now you should call the shell script CA.sh +to set up the initial database: + + CA.sh -newca + +This command will ask you whether you want to use an existing certificate or +create one. Just press enter to create a new key pair and certificate. You +will be asked the usual questions for certificates: the country, state, city, +"Common Name", etc. Enter the appropriate values for the CA. When CA.sh +finishes, it has set up a bunch of directories and files. A CA must publish +it's certificate, which is in the file "/usr/local/ssl/CA/cacert.pem". + + +How to sign a certificate request +================================= +After setting up the CA stuff, you can start signing certificate requests. +Make sure that the SSLeay utilities know where the configuration file is. +The default is compiled in, if you don't use the default location, add the +parameter "-config <cfg-file>". Make also sure that the configuration file +contains the correct path to the CA database. If all this is set up properly, +you can sign the request in the file "csr.pem" with the command: + + openssl ca -policy policy_anything -days 365 -infiles csr.pem >cert.pem + +The resulting certificate (and additional information) will be in "cert.pem". +If you want the certificate to be valid for a period different from 365 days, +simply change the "-days" parameter. + + +How to install a new CA certificate +=================================== +Whereever a certificate must be checked, the CA's certificate must be +available. Let's take the common case where the client verifies the server's +certificate. The case where the server verfies the client's certificate works +the same way. The client receives the server's certificate, which contains +the "Distinguished Name" of the CA. To verify whether the signature in this +certificate is OK, it must look up the public key of that CA. Therefore each +client must hold a database of CAs, indexed by CA name. This database is best +kept in a directory where each file contains the certificate of one CA and is +named after the hashvalue (checksum) of the CA's name. This section describes +how such a database is managed technically. Whether or not to install (and +thereby trust) a CA is a totally different matter. + +The client must know the directory of the CA database. This can be configured. +There may also be a configuration option to set up a CA database file which +contains all CA certs in one file. Let's assume that the CA database is kept +in the directory "/usr/local/ssl/certs". The following example assumes that +the CA's certificate is in the file "cacert.pem" and the CA is known as +"myCA". To install the certificate, do the following: + + cp cacert.pem /usr/local/ssl/cers/myCA.pem + cd /usr/local/ssl/certs + ln -s myCA.pem `openssl x509 -noout -hash < myCA.pem`.0 + +The last command creates a link from the hashed name to the real file. + +From now on all certificates signed by the myCA authority will be accepted by +clients that use the directory "/usr/local/ssl/certs/" as their CA certificate +database. + + + |