SSLPi

secure communication for the raspberry pi. The main focus is on easy installation and no need for any cloud service. A direct communication between a raspberry pi an clients with the use of OpenSSL. With the help of a configuration file you are able to implement your own applications onto the raspberry pi.

You'll find a German translated Version of the ReadMe at www.iot4pi.com .

So let's get started with the installation:

After downloading the IoT4pi-SSLPi-XXXX.tar.gz to your System (Raspberry pi) to any given directory and extract it with the command

`$ tar -zxvf IoT4pi-SSLPi-XXXX.tar.gz`

this generate a directory IoT4pi-SSLPi-XXXX. (The X will vary depending on the version you have downloaded)

Change into the directory with

`$ cd IoT4pi-SSLPi-XXXX`

There you will see with "ls -l"

pi@Mypi ~/SSLPi_VersX $ ls -l
drwxr-xr-x 2 pi pi  4096 Jan 27 13:12 app
drwxr-xr-x 2 pi pi  4096 Jan 27 13:12 Test
-rwxr-xr-x 1 pi pi  6656 Jan 27 14:23 Install.sh
-rw-r--r-- 1 pi pi  4923 Jan 27 15:30 ReadMe_Install
-rw-r--r-- 1 pi pi  4923 Jan 27 15:30 ReadMe_Config
-rw-r--r-- 1 pi pi  4923 Jan 27 15:30 SSLPi.cfg
-rw-r--r-- 1 pi pi 21557 Jan 27 15:24 SSLserverPi_VX.py
-rwxr-xr-x 1 pi pi   550 Jan 27 15:30 startSSLPi.sh

In the app directory are sample application, to show you how to configure the SSLPi to your own demands.

In the TestClient directory is a sample Python SSL Client You can use it and modify it to your own needs. It is tested to work together with SSLPi Server.

To start the installation type

$ sudo ./Install.sh

The script is going to proof if the prerequisite software is on your system. It actually checks if the Python2.7 and OpenSSL is installed. If not, it will exit the install script and you have to install the missing software.

As an information: you can install OpenSSL with $ sudo apt-get install openssl

you can install python with $ sudo apt-get install python2.7 But I do not think this will happen very often,because the Raspberry (& Raspian) runs Python 2.7 out of the box

Next you will be asked for directory, where the SSLPi Server has to be installed. If you do not specify a directory, the default directory will be created. the default directory is /home/pi/SSLPi/

Next type in where to install the certificates. The default directory is /home/pi/SSLPi/Cert/

As a next step the script is creating the certificates. You have to type in a password three times. It has to be the same password, all the time.

Afterwards you are asked for several pieces of information. *One of the prompts will be for "Common Name (e.g., YOUR name)". It is important * that this field be filled in with the fully qualified domain name of the server to be protected by SSL.

`Country Name (2 letter code) [GB]:DE`
`State or Province Name (full name) [Berkshire]:Bavaria`
`Locality Name (eg, city) [Newbury]:Munich`
`Organization Name (eg, company) [My Company Ltd]:IoT4pi`
`Organizational Unit Name (eg, section) []:Information Technology`
`!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`
`!!!!!Common Name (eg, your name or your server's hostname) []:iot4pi.com !!!!!!!!`
`!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!`
`Email Address []:office@iot4pi`
`Please enter the following 'extra' attributes`
`to be sent with your certificate request`
`A challenge password []:`
`An optional company name []:`

If you have everything provided, the the script will finish successfully. The server will now start automatically at the reboot of the Raspberry pi. Per default the server will listen at port 10023.

You can now proof that everything is running OK by:

Testing if it starts at Boot with command 
        `$sudo crontab -l`
        `it should present a line like:`
        `@reboot sudo /home/pi/SSLPi/startSSLPi.sh >> /home/pi/SSLPi/log 2>&1`


after reboot you can test if the server is running with
        `$ ps aux | grep SSLserverPi`
        `this should bring something like`

        `root 2133 0.0  0.5  4592 2640 ?  S  08:49 0:00 sudo python /home/pi/SSLPi/SSLserverPi_VX.py`

You will find the Server application in the specified installation directory. In this directory there will be the app directory with the sample scripts. The Certificates will be stored in the specified certification directory. There you will find

`-rw-r--r-- 1 root root 1147 Jan 27 15:31 server.cer`
`-rw-r--r-- 1 root root 1679 Jan 27 15:30 server.key`
`-rw-r--r-- 1 root root 1751 Jan 27 15:30 server.orig.key`
`-rw-r--r-- 1 root root 1338 Jan 27 15:31 server.pem`

The file server.pem is the important file you will need for the clients. This file you have to copy and provide your clients with it. This one is the key to establish a communication withe the server. Without it, the server would reject any communication attempt.

After you have successfully installed the software you can configure the SSLserverPi

to your own needs. This has to be done with the File SSLPi.cfg. The configuration file SSLPi.cfg has to be stored in the same directory as the SSLserverPi_VersX.py.

The Configuration is separated in two sections. The section [SETUP] takes care of the global behavior of the server. The section [APP_CALLS] is the part where you call your own applications on the Raspberry pi. To give you an idea how it is done, we provide you with a few APP Call's and the referring applications/scripts which are stored in the directory app.

Per default the server will listen at port 10023. If you want to change the Port, go to the section [SETUP] and change the line iPort:10023 Everything else can be left unchanged in section [SETUP], if you have installed the server with the Install.sh.

The section [APP_CALLS] takes care of the Configuration of the applications which have to be proceeded by the Server. A call is initiated by a Command which is sent from the Client to the Server. An App Call can consist of one or more commands of the the server. Therefore an APP_CAll has a special format.

The format of APP_CALLS configuration Line is specified like this:

No. : Command_In ; Sequence # ; OS Command ; App+Path ; Type ; Success Return ; Arg 1 ; ..; Arg n

All entry have running Number and a Name called Command_In. The Command_In is the command which could be called by a Client. The Command_In is the name of the APP_CALL. An APP_CALL will sent by the Client to the Server by the Command_In String. A Command_In/APP_CALL can have non or one Parameter !

Due to the fact that an APP_CALL can consist of more then on command, we have to specify in which order the commands have to be proceeded by the the server. This order is specified by the sequence number Sequence Number.

The Value of OS Command can only be True or False. In case of an OS Command the App+Path needs only the command. The operating systems takes care of the rest.

The App+Path should be the full Path and Name of the Command, except a OS Command is used. Test is a special command, it is an internal command which will send a Test Message back to the Client. You also have to take care in the Type column using the Test command.

The Type is needed by the Server, because depending on the Command Type it has to be handled different. Following Types are defined:

`Test Command (sends back Test message)         -- Value 0`
`Change Dir                                         -- Value 1`
`(with defined directory in Argument section)`
`Command without a return (like rm )            -- Value 2`
`Command with return (like ls or pwd)           -- Value 3`
`Command  handles the parameters, with return       -- Value 4`
`Command  handles the parameters, without return         -- Value 5`
`Command  handles the parameters,for Change Dir     -- Value 6  `
`Command with asynchron return value                    -- Value 7`

As you see there are already 8 types defined. There are four groups.

`1) Value 0: the Test command which is an internal Test Function`
`2) Value 1 to 3: are Commands which will be proceeded by the Server without a Parameter`
`3) Value 4 to 6: the command which has to handle the parameter which is sent by the Client  `
`4) Value 7: Run the command asynchronously. Program is called on the Raspberry and it is unpredictable when` 
            `a feedback comes. This is used for so-called push notifications.`

So, as already mentioned one APP_CALL (Command_In) can consist of more then one commands. If the APP_CALL (Command_In) is sent with one Parameter you have to define which command in the sequence will take care of this parameter. See the configured examples in the SSLPi.cfg.

*Info: * All commands of one APP_CALL of a Client are proceeded in one run. The server won't interrupt to handle an other Client in-between. Therefore it is guaranteed that you can edit files, change directories and set IO's in one APP_CALL.

Success Return: specifies which values the the sever gets, if the launched command was successfully processed. Normally you will 0 or 1 but sometimes you can not predict what you will get but you can define what you do not want to get. In this case use the Reply string {!} (= must NOT be) with return Value (for instance {!}ERROR).

The last column is for arguments. If a command should have an additional parameter, it is defined in the argument. For instance "ls -l" would be separated this way : "ls" into the App+Path column and "-l" as an argument.