+++ /dev/null
-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.
-
-
-
projects / thirdparty / samba.git / commitdiff
