9. Advanced Topics

9.1 Encrypted Data Transfer with SSL

In this section, we assume that you are familiar with the basics of cryptography. If you don't know what the words "encryption", "digital signature" and "RSA" mean, please read one of the introductions available. A good starting point might be part 6 and 7 of the cryptography FAQ which is posted to the usenet newsgroup sci.crypt. It is also available from

    ftp://rtfm.mit.edu/pub/usenet/news.answers/cryptography-faq

    http://www.cis.ohio-state.edu/hypertext/faq/usenet/cryptography-faq

What is SSL and SSLeay/OpenSSL?
SSL (Secure Socket Layer) is a protocol for encrypted and authenticated data transport. It was developed for secure web servers for shopping malls, telebanking and things like that. Because SSL is not specific for the http protocol, it can also be used for telnet, ftp, POP3 and many other protocols.

SSLeay is a free implementation of the SSL protocol. It is available from

    ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/

Encryption is plagued by legal problems of all kinds. For a discussion of these problems please read the documentation of SSLeay, which is available at

    http://www.psy.uq.edu.au/~ftp/Crypto/

Compiling Sharity with OpenSSL

1. Get and install OpenSSL. We'll assume that you install it at the default location, which is "/usr/local/ssl/". For other locations please change all absolute pathes referenced in this manual accordingly. This version of Sharity has only been tested with OpenSSL 0.9.1. OpenSSL can be compiled with a simple "make" in the top level directory on most platforms. It won't be optimized if you do that, but it will run.
2. Modify Sharity's Makefile.config. Search for "SSL" to find the SSL section. Uncomment the definitions and modify SSLROOT if necessary.
3. Compile and install as usual.
4. Use the GUI tool to set the pathes to relevant SSL files (certification authrorities, certificate, private key, ...), or edit cfgdb.ppl by hand if you have no GUI. Note that the GUI can not configure all SSL settings to make things simpler. You are, for instance, restricted to using a file with certification authorities, not a hashed directory.

About Certificates
Encryption is not sufficient to establish a really secure connection. You need a kind of proof that the other side is really who it pretends to be. If the communication partners have never met, the only way of proof is a common authority that both parties trust. This authority digitally signs the binding of a (public) encryption key and the party's name. This signed data block is the certificate and the autority is called Certification Authority (CA).

There has always been some confusion about the significance of certificates. In fact, there is no general answer to this question. The CA confirms something by signing the certificate. But the subject of this confirmation can be freely chosen by the CA itself. There might be a CA that signs everything it gets. You would better not add this CA to your list of trusted CAs, of course. Most CAs in the web simply 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.

For a secure CIFS server you will most probably not want to get certificates from a well known CA. For the typical application of a distributed office you will want to operate a company-wide CA yourself. This company-wide CA can have its own policy for signing certificates. The policy "All our servers and all our clients will get a certificate and no one else" is probably a good idea.

Setting up OpenSSL
Because you will probably have to operate your own CA and install certificates for servers an clients, here's a short introduction how to do it with 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   

    cat >/tmp/rfile.txt

    openssl genrsa -rand /tmp/rfile.txt > /dev/null
    rm -f /tmp/rfile.txt

How to create a Keypair
Certificates are specific for a (public) key. If you want to use a certificate, you also have to use a constant keypair. A file containing a random keypair is created with genrsa for RSA keys and gendsa for DSA keys. For an RSA key with 512 bits which is written to the file "key.pem" type:

    openssl genrsa -des3 512 > key.pem

If you want to remove the pass phrase from a key use:

    openssl rsa -in key.pem -out newkey.pem

    openssl rsa -des3 -in key.pem -out newkey.pem

How to create a Dummy Certificate
If you don't need certificates at all (this is recommended only for testing!), you can't simply omit the certificate file on the server. An SSL server must have a certificate. The simplest way to create a dummy certificate is as follows:

If you still have your keypair in the file "key.pem", the command

    openssl req -new -x509 -key key.pem -out cert.pem

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

How to set up a Certification Authority
Being a certification authority requires a database that holds the CA's keypair, the CA's certificate, a list of all signed certificates and some other information. This database is kept in a directory hierarchy below a configurable starting point. The starting point must be configured in the "openssl.conf" file. This file is at "/usr/local/ssl/lib/openssl.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/

    CA.sh -newca

How to sign a Certificate Signing Request
After setting up the CA stuff, you can start signing certificate requests. Make sure that the OpenSSL 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

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. The "Distinguished Name" consists of the information you gave when the CA was set up and the CA's certificate was created. To verify whether the signature in this certificate is OK, the client 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

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.

9.2 The Configuration File

Both configuration files are parsed when the daemon starts and when a HUP signal is sent to the daemon. You can therefore edit the configuration and make the changes effective without restarting the daemon. Please note that not all configuration changes can work immediately. Many options are read into internal variables when they are used. Much of the server configuration, for instance, is transferred into internal structures when a connection to the server is opened. Therefore, if a change to the server configuration should become active, you should first unmount all shares and log out all users from that server.

General Strucute
Configuration files are built from the following simple syntactic structures:

• remarks
• strings
• arrays
• dictionaries

Remarks can be written in three forms:

    /* remark */

    // remark to end of line

    # remark to end of line

Strings are sequences of alphanumeric characters, including the underscore. If a string should consist of other characters like spaces, it must be quoted in double quotes. Within double quotes, the same escape-sequences as in C strings can be used. There is no separate syntax for numeric arguments. Since numbers are read as strings and converted when they are used, you must quote negative numbers because they begin with a minus sign.

Arrays are ordered lists of other properties. An array is delimited by parentheses and the properties constituting the array may be separated by commas. The following example is an array consisting of several string elements:

    (1, 2, 3, hello, "how are you")

Dictionaries are unordered lists of named properties. They are delimited by curly braces. Each dictionary entry consists of a left hand side (key), which must be a string, an equal sign and a right hand side (value) which may be any property. Entries may be separated by semicolons. The following is an example of a dictionary consisting of three entries named "property1" to "property3" where the first one has a string value, the second an array value and the third a dictionary value:

    {
        property1 = "value of property1";
        property2 = (value, of, property2);
        property3 = {
            firstWord = value;
            secondWord = of;
            thirdWord = property3;
        };
    }

Properties that have been parsed as strings may be interpreted in one of the following ways:

• string
• number
• enumeration
• boolean

Configuration Variables
It's not useful to describe the configuration variables here in the manual. It's better to see them in context in the configuration file. The file sharity.cfg contains all possible configuration variables along with their description in a remark. Please see this file for more information.

9.3 Sharity as a Framwork for Virtual Filesystems