From 0d76ac63315545c530b251bd4c27c7ac53d1c632 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Thu, 27 Sep 2001 03:40:34 +0000 Subject: sync up with 2.2 (This used to be commit 9d8cbf3d5db35df6aa50636a48444caf10441c8c) --- docs/textdocs/SSLeay.txt | 405 ---------------------------------------- docs/textdocs/Samba-OpenSSL.txt | 405 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 405 insertions(+), 405 deletions(-) delete mode 100644 docs/textdocs/SSLeay.txt create mode 100644 docs/textdocs/Samba-OpenSSL.txt (limited to 'docs') diff --git a/docs/textdocs/SSLeay.txt b/docs/textdocs/SSLeay.txt deleted file mode 100644 index e1b54b1a03..0000000000 --- a/docs/textdocs/SSLeay.txt +++ /dev/null @@ -1,405 +0,0 @@ -Contributor: Christian Starkjohann -Date: May 29, 1998 -Status: - -Comment: Updated by Lutz Jaenicke -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 ". 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. - - - 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 +Date: May 29, 1998 +Status: + +Comment: Updated by Lutz Jaenicke +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 ". 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. + + + -- cgit