Merge pull request #13 from MicrochipTech/develop

Update with improvements

Author: bryan-hunt

.gitmodules

@@ -1,48 +1,81 @@
 
-#CryptoAuthentication OpenSSL Engine  
+Configuration:
 
-##Overview
-This is an OpenSSL Engine implementation using ATECC508A for ECC key storage, ECDSA sign/verify, ECDH, and FIPS Random Number Generator
+Most of the configuration of the library can be done in lib/openssl/eccx08_engine.h or via defines during build
 
-The implementation integrates the [Atmel ATECC508A](http://www.atmel.com/devices/atecc508a.aspx) into the [OpenSSL ENGINE API](http://openssl.org/docs/manmaster/crypto/engine.html) to provide secure hardware key storage, [CAVP certified random numbers](http://csrc.nist.gov/groups/STM/cavp/documents/aes/aesval.html), P256 ECDSA & ECDH, and secure storage for data.
+The exception to this is in eccx08_platform.c where key slots are defaulted 
 
-This project will integrate the key creation and import capabilities of the ATECC508A into the OpenSSL key creation and certificate creation process. 
+If the ATCA_OPENSSL_ENGINE_STATIC_CONFIG define is set to 1 then device and signer certificate definitions will
+have to be linked into the library at build. 
 
-Also, secure key storage for RSA keys are implemented using the encrypted read/write feature of the ATECC508A. 
+e.g. see the line in the makefile: #LIBATECCSSL_OBJECTS += cert_def_1_signer.c cert_def_2_signer.c
 
-###Supported Cipher Suites
-Many ECDH(E)-ECDSA and ECDHE-RSA cipher suites are supported with the OpenSSL Engine for ATECC508A implementation.  
 
-Details for cipher suites can be found [here](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Supported-Ciphers)
+Makfile:
 
-##Download and Make 
-Build instructions for Linux can be found on the Wiki pages associate with this project.
+The makefile included in this archive is fairly basic and is not what one would consider appropriate for a package
+so there is likely some manual configuration that would be needed at this stage
 
-See: [Compile OpenSSL Engine for ATECC508A on Linux](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Linux:-Compile-OpenSSL-Engine-for-ATECC508A)
 
-##Platform Integration
-Follow the platform integration instructions found [here](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Integrate-ATECC508A-onto-Your-Platform)
+To build the library:
 
-##Unit Tests
-Unit testing is provided for both integration of the ATECC508A device and OpenSSL Examples.  
-For details see:
-[Platform Integration Tests](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/ATECC508A-Integration-Tests)
-[OpenSSL Engine Tests & Examples](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Tests-And-Examples)
+> make libateccssl
 
-Source-Level Documentation
-Full Doxygen source-level documentation is provided.
-See: /docs/doxygen/html/index.html
+To run the test program:
 
-##Web Server Setup
-The OpenSSL Engine for ATECC508A can also be configured. 
-See Details [here](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Web-Server-For-The-Web-Browser).
+> make test
 
-##Wiki Topics:
-- [Linux Development Setup](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Linux:-Development-Setup)
-- [Compiling on Linux](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Linux:-Compile-OpenSSL-Engine-for-ATECC508A)
-- [Debugging on Linux](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Linux:-Debugging)
-- [ATECC508A Integration](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/ATECC508A:-Platform-Integration)
-- [ATECC508A Certificate Provisioning](http://www.atmel.com/tools/at88ckeccroot-signer.aspx)
-- [Tests and Examples](https://github.com/AtmelCSO/cryptoauth-openssl-engine/wiki/Tests:-OpenSSL-Tests-and-Examples)
+To extract certificates (if the engine is added to the openssl.cnf file):
 
+> openssl engine ateccx08 -t -post GET_DEVICE_CERT:./device.der
+> openssl engine ateccx08 -t -post GET_SIGNER_CERT:./signer.der
 
+Otherwise you'll have to use an interactive openssl session (see openssl engine -h and engine -vvv for details)
+
+> openssl
+
+OpenSSL> engine dynamic -pre SO_PATH:/<full path to libeccssl.so> -pre LIST_ADD:1 -pre ID:ateccx08 -pre LOAD
+OpenSSL> engine ateccx08 -t -post GET_DEVICE_CERT:./device.der
+OpenSSL> engine ateccx08 -t -post GET_SIGNER_CERT:./signer.der
+
+Then to verify the certs:
+> openssl x509 -in device.der -inform der -text -noout
+> openssl x509 -in signer.der -inform der -text -noout
+
+To set up your openssl.cnf file
+
+Find which openssl.cnf file your instance is using you can:
+
+> openssl version -a | grep OPENSSLDIR
+OPENSSLDIR: "/usr/lib/ssl"
+
+will tell you the base location where openssl is looking for the openssl.cnf file. It may be a symbolic link to another location
+
+> ls -l /usr/lib/ssl
+lrwxrwxrwx 1 root root 14 Apr 24 15:22 certs -> /etc/ssl/certs
+lrwxrwxrwx 1 root root 20 Jan 31 05:53 openssl.cnf -> /etc/ssl/openssl.cnf
+
+To set up the openssl.cnf to use the engine:
+
+# At the top:
+
+openssl_conf = openssl_init
+
+# Append to the end:
+
+[ openssl_init ]
+engines = engine_section
+
+[ engine_section ]
+ateccx08 = ateccx08_config
+
+[ ateccx08_config ]
+engine_id = ateccx08
+# Or if you sym link the libateccssl.so to the engine directory the next line is not needed
+dynamic_path = <full path to libateccssl.so>
+device_key_slot = 0
+init = 0
+
+To use the engine in an application you can reference the openssl tests (test/openssl/test_engine.c) but the basic principle is that
+if the openssl.cnf file is configured correctly all an application really needs to do is add a call to OPENSSL_config if it is not already
+doing so and then to decide what functionality that the application wants and register it.