Table of ContentOverview PagePrevious PageNext Page

9. Advanced Topics

9.1 Encrypted Data Transfer with SSL

Sharity can be compiled with SSL (Secure Socket Layer) support. Sharity with SSL support is different from a normal Sharity run through an SSL converter: Server and client can automatically negotiate SSL mode. This mode of operation is currently supported by Samba and by SSL Proxy (available from our web site), which can transform any CIFS server into an SSL CIFS server.

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

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
SSLeay has been superceded by OpenSSL. The home of OpenSSL is

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
To compile Sharity with SSL support, you must first compile and install SSLeay or OpenSSL (we will use the namem OpenSSL in the rest of the text, you may substitute SSLeay if you like). OpenSSL consists of a library (which can be linked to other applications like Sharity and Samba) and several utility programs needed for key generation, certification etc. The current version of Sharity has been tested with OpenSSL version 0.9.0. It should work with 0.8.x, too, although it may require some fine-tuning.

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.:

Then you should set up OpenSSL's random number generator. The state of this random number generator is held in the file ".rnd" in your home directory. To set a reasonable random seed, you need random data. Create a random file with
    cat >/tmp/rfile.txt
Then type random keys on your keyboard for about one minute. Then type the EOF character (^D) to terminate input. You may also use your favorite editor to create the random file, of course. Now you can create a dummy key to initialize the random number generator:
    openssl genrsa -rand /tmp/rfile.txt > /dev/null
    rm -f /tmp/rfile.txt
Don't forget to delete the file "/tmp/rfile.txt". It's more or less equivalent to your private key!

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
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 "512". 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 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
will write a self-signed dummy certificate to the file "cert.pem". 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
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 "", which should be at "/usr/local/ssl/bin/". Change the path in the shell script:

    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 OpenSSL as CA user (set up the random number generator). Now you should call the shell script "" to set up the initial database: -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 "" finishes, it has set up a bunch of directories and files. A CA must publish its certificate, which is in the file "/usr/local/ssl/CA/cacert.pem".

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
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. 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
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.

9.2 The Configuration File

Sharity's configuration is governed by two configuration files: sharity.cfg and cfgdb.ppl. The name and path of the first one can be given on the daemon's commandline, the name and path of the second is configured in sharity.cfg. These two files are hierarchical in most parts: Settings in cfgdb.ppl can override the defaults in sharity.cfg (except for some very basic settings in the main section). sharity.cfg contains the factory defaults and cfgdb.ppl contains the configurations you make from the GUI application.

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
Strings, arrays and dictionaries are also called properties.

Remarks can be written in three forms:

    /* remark */
as in C,
    // remark to end of line
as in C++ or Objective-C and
    # remark to end of line
as in shell scripts.

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;
The configuration file itself is a dictionary (the sourrounding curly braces are optional because other properties are not allowed). By convention, the top level keys are related to modules. Each module should have only one key at the top level which is a dictionary containing the module's configuration.

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

  • string
  • number
  • enumeration
  • boolean
"String" needs no further explanation. Numbers are interpreted in decimal, unless they are prefixed with 0 (meaning octal) or 0x (meaning hexadecimal). Enumerations are strings from a predefined set of strings. And boolean variables are a special case of enumeration where the set consists of the stings "yes" and "no".

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

As already mentioned, Sharity 2 is more than just a CIFS client. It's also a framework for mapping arbitrary data into the filesystem by arbitrary means. There's a frontend, which implements the actual connection to the filesystem, and a backend, which provides the data that's mapped. Frontends and backends can be loadable modules. For more information, please see the developer documentation at source/doc/developer/.

Table of ContentOverview PagePrevious PageNext Page

Sharity Manual 2.9 Beta 7 | Copyright (C) 2004 OBJECTIVE DEVELOPMENT Software GmbH |