diff options
| -rw-r--r-- | docs/textdocs/Samba-OpenSSL.txt | 405 |
1 files changed, 0 insertions, 405 deletions
diff --git a/docs/textdocs/Samba-OpenSSL.txt b/docs/textdocs/Samba-OpenSSL.txt deleted file mode 100644 index e1b54b1a03..0000000000 --- a/docs/textdocs/Samba-OpenSSL.txt +++ /dev/null @@ -1,405 +0,0 @@ -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. - - - |