Various improvements and ruggedizations

Improvements include the following:
- Include Pipfile for easily setting a Pipenv virtual environment for running the Python examples
- Improved README build instructions for libsodium and Python examples
- Ruggedized libsodium CMake build to help prevent linker errors on some platforms
- Improved comments in nacl_encrypt_file.c libsodium file encryption example to warn that it is suitable only for files which can fit in the computer's RAM and a stream-based encryption should be used for larger files

Author: tleonhardt

.gitignore

@@ -54,6 +54,8 @@ dkms.conf
 # Python
 __pycache__
 *.pyc
+.venv
+Pipfile.lock
 
 * CLion and/or PyCharm IDEs
 .idea

Pipfile

@@ -0,0 +1,12 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+ipython = "*"
+
+[packages]
+cryptography = "*"
+colorama = "*"
+pynacl = "*"

README.md

@@ -93,6 +93,81 @@ use the cryptography module.
 Building
 ========
 
+libsodium C examples
+--------------------
+
+The [libsodium](https://download.libsodium.org/doc/) C code examples are all in the **sodium** directory and can be 
+built using the [Cmake](https://cmake.org) cross-platform build tool along with your platform default C compiler
+installed on Windows, macOS, or Linux.
+
+The first stage of building is the same on all platforms:
+
+```bash
+cd sodium
+rm -rf build
+mkdir build
+cd build
+cmake ..
+```
+
+The second stage of building is platform dependent and will create the following executable files:
+
+* hello_sodium
+* nacl_keygen
+* nacl_sign
+* nacl_verify
+* symmetric_decrypt
+* symmetric_encrypt
+* symmetric_keygen
+* test_ed25519
+* test_pynacl_compatibility
+
+### Linux or macOS
+```bash
+make
+```
+
+This produces the  executable files directly in the **build** directory.
+
+### Windows
+```bash
+devenv hello_sodium.sln /build Debug
+```
+This creates the executable files under the **build\Debug** directory.
+
+Python examples
+---------------
+
+The Python examples are located in the root directory and should work with Python 3.4 or newer.  The Python examples 
+require a mix of the following Python packages:
+
+* [cryptography](https://cryptography.io/en/latest/) - high-level wrapper around [OpenSSL](https://www.openssl.org)
+* [pynacl](https://pynacl.readthedocs.io/en/stable/) - Python binding to [libsodium](https://libsodium.org)
+* [colorama](https://github.com/tartley/colorama) - cross-platform colored terminal text
+
+The required dependencies can easily be installed using [Pipenv](https://github.com/pypa/pipenv):
+```shell script
+pipenv install
+```
+
+Then a shell using the underlying virtual environment can be entered with:
+```shell script
+pipenv shell
+```
+
+Inside that Pipenv shell, any of the examples can be ran directly. e.g.:
+```shell script
+python ./aes_gcm_cryptography.py
+```
+
+The Python examples are intended to interoperate with either the libsodium or mbedTLS C code examples.  Thus encryption
+or signing can be done in C and decryption or verifying can be done in Python or vice versa.
+
+mbedtls C examples
+------------------
+The [mbedTLS](https://github.com/ARMmbed/mbedtls) C code examples are located in the root directory and build mbedTLS
+from source from the **mbedtls** directory.
+
 Build requires CMake and platform default C compiler installed and works on both Windows, macOS, and Linux.
 
 The first stage of building is the same on all platforms:
@@ -106,8 +181,7 @@ cmake ..
 
 The second stage of building is platform dependent ...
 
-Linux or macOS
---------------
+### Linux or macOS
 ```bash
 make
 ```
@@ -120,8 +194,7 @@ This produces the following executable files directly in the **build** directory
 * kdf
 * rsa_signature
 
-Windows
--------
+### Windows
 ```bash
 devenv mbed_AES.sln /build Debug
 ```

sodium/CMakeLists.txt

@@ -5,9 +5,17 @@ project("hello_sodium" C)
 set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -O2 -Wall")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11 -g -O2 -Wall")
 
+# Set the CMAKE_MODULE_PATH so it can find the Findsodium.cmake file
+set(CMAKE_MODULE_PATH
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake"
+        ${CMAKE_MODULE_PATH})
+
 # Projects which statically link Sodium in Visual Studio must define a macro named SODIUM_STATIC
 add_definitions(-DSODIUM_STATIC)
 
+# Find where libsodium is installed (prevent linker errors)
+find_package(sodium REQUIRED)
+
 # Tell CMake where to look for header files
 include_directories(${CMAKE_SOURCE_DIR}/include)