Added credentials documentation

1 files changed, 80 insertions, 23 deletions

diff --git a/doc/rvi_protocol.md b/doc/rvi_protocol.md
index e677579..58bf26e 100644
--- a/doc/rvi_protocol.md
+++ b/doc/rvi_protocol.md
@@ -7,12 +7,12 @@ Attribution-ShareAlike 4.0 International.
 This document describes the core protocol between two RVI nodes.
 
 # STANDARDS USED
-[1] Transport Layer Security - TLS (link)[https://tools.ietf.org/html/rfc5246]
-[2] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32]
-[3] MessagePack - (link)[http://msgpack.org/index.html]
-[4] base64url - (link)[https://en.wikipedia.org/wiki/Base64)
-[5] Transport Layer Security (TLS) - (link)[https://en.wikipedia.org/wiki/Transport_Layer_Security]
-[6] X.509 Certificates - (link)[https://en.wikipedia.org/wiki/X.509]
+[1] Transport Layer Security - TLS (link)[https://tools.ietf.org/html/rfc5246]<br>
+[2] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32]<br>
+[3] MessagePack - (link)[http://msgpack.org/index.html]<br>
+[4] base64url - (link)[https://en.wikipedia.org/wiki/Base64)<br>
+[5] Transport Layer Security (TLS) - (link)[https://en.wikipedia.org/wiki/Transport_Layer_Security]<br>
+[6] X.509 Certificates - (link)[https://en.wikipedia.org/wiki/X.509]<br>
 
 # FEATURES COVERED BY PROTOCOL
 1. **Authroization**<br>
@@ -179,22 +179,24 @@ This chapter describes the protocol message formats and how the various fields a
 
 For all examples below the following certifcates are used:
 
-## Reference root certificate
+## Sample root certificate
 The self signed root certificate used in the examples throughout this
 document was generated using the following commands:
 
 ```Shell
 # Create root key and cert signing request
-openssl req -new -newkey rsa:1024 -nodes -out root_cert.csr -keyout root_key.pem
+openssl req -new -newkey rsa:1024 -nodes -out insecure_root_cert.csr -keyout insecure_root_key.pem
 
 # Create the CA-like root cert,
-openssl x509 -trustout -signkey root_key.pem -days 365 -req -in root_cert.csr -out root_cert.crt
+openssl x509 -trustout -signkey insecure_root_key.pem -days 365 -req \
+             -in insecure_root_cert.csr -out insecure_root_cert.crt
 ```
 
-The ```root_cert.csr``` intermediate certificate signing request can
+The ```insecure_root_cert.csr``` intermediate certificate signing request can
 be deleted once the two steps above have been executed.
 
-The content of the reference ```root_key.pem``` private key file is:
+The content of the sample ```insercure_root_key.pem``` private key
+file, which has no password protection, is:
 
 ```
 -----BEGIN PRIVATE KEY-----
@@ -202,9 +204,8 @@ TBD
 -----END PRIVATE KEY-----
 ```
 
-The root private key has no password protection.
 
-The content of the reference ```root_cert.crt``` file is:
+The content of the sample ```insecure_root_cert.crt``` file is:
 
 ```
 -----BEGIN TRUSTED CERTIFICATE-----
@@ -212,25 +213,55 @@ TBD
 -----END TRUSTED CERTIFICATE-----
 ```
 
-## Reference device certificate
+These files are checked into ```priv/sample_certs``` and ```priv/sample_keys```.
 
-The reference device x.509 certificate, signed by the root certificate above,
+** DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION! <br>
+ANY PRODUCTION KEYS SHOULD BE GENERATED BY THE ORGANIZATION AND BE 4096 BITS LONG. **
+
+## Sample device certificate
+
+The sample device x.509 certificate, signed by the root certificate above,
 was generated with the following command:
 
 ```Shell
 # Create the device key. In production, increase the bit size to 4096+
-openssl genrsa -out device_key.pem 1024
+openssl genrsa -out insecure_device_key.pem 1024
 
 # Create a certificate signing requestsigning request
-openssl req -new -key device_key.pem -out device_cert.csr
+openssl req -new -key insecure_device_key.pem -out insecure_device_cert.csr
 
 # Sign the signing request and creaqte the root_cert.crt file
-openssl x509 -req -days 365 -in device_cert.csr -CA root_cert.crt -CAkey root_key.pem -set_serial 01 -out device_cert.crt
+openssl x509 -req -days 365 -in insecure_device_cert.csr \
+             -CA insecure_root_cert.crt -CAkey insecure_root_key.pem \
+             -set_serial 01 -out insecure_device_cert.crt
+```
+
+
+The ```insecure_device_cert.csr``` intermediate certificate signing
+request can be deleted once the three steps above have been executed.
+
+The content of the sample ```insercure_device_key.pem``` private key
+file, which has no password protection, is:
+
+```
+-----BEGIN PRIVATE KEY-----
+TBD
+-----END PRIVATE KEY-----
+```
+
+
+The content of the sample ```insecure_device_cert.crt``` file is:
+
+```
+-----BEGIN TRUSTED CERTIFICATE-----
+TBD
+-----END TRUSTED CERTIFICATE-----
 ```
 
+These files are checked into ```priv/sample_certs``` and ```priv/sample_keys```.
 
-The ```device_cert.csr``` intermediate certificate signing request can
-be deleted once the three steps above have been executed.
+** DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION! <br>
+ANY PRODUCTION KEYS SHOULD BE GENERATED BY THE ORGANIZATION AND BE 4096 BITS LONG. **
 
 
 ## RVI credentials format
@@ -291,16 +322,42 @@ The members are as follows:
 
 Member              | Description
 --------------------|---------------------
-create\_timestamp   | Unix timestamp of when the certificate was created
+create\_timestamp   | Unix timestamp of when the credential was created
 right\_to\_invoke   | A list of service prefixes that the sender has the right to invoke on any node that has registered matching services that start with the given string(s).
 right\_to\_register | A list of services that the sender has the right to to register for other nodes to invoke.
-id                  | A system-wide unique identifier for the certificate.
+id                  | A system-wide unique identifier for the credential.
 iss                 | The issuing organization.
 device_certificate  | The PEM-encoded device X.509 certificate to match against the sender's TLS certificate.
-validity            | The Unix timestamps within when the certificate is valid.
+validity.start      | The Unix timestamps when the credential becomes active.
+validity.stop       | The Unix timestamps when the credential becomes inactive.
 
 ## Generating RVI credentials
 
+To create a credential, tie it to a device X.509 certificate, and sign it with a root X.509 certificate private key, the following command is used:
+
+
+```Shell
+rvi_create_credential.py --cred_out="insecure_credential.json" \
+                         --jwt_out='insecure_credential.jwt' \
+                         --id="xxx" \
+                         --issuer="genivi.org" \
+                         --root_key=insecure_root_key.pem \
+                         --device_cert=insecure_device_cert.crt \
+                         --invoke='genivi.org/' \
+                         --register='genivi.org/'
+```
+
+The following command line parameters are accepted:
+
+Parameter      | Required | Description
+-------------- | -------- | ---------
+--cred\_out    | No       | Output file containing the JSON-formatted un-encoded credential.
+--jwt\_out     | Yes      | JWT-encoded, JSON-formatted, root keyp-signed credential.
+--issuer       | Yes      | Organization that issued the credential.
+--root\_key    | Yes      | Private, PEM-encoded root key to sign the credential. Must be the same key used to sign the root X.509 certificate.
+--device\_cert | Yes      | The PEM-encoded device X.509 certificate to embed into the credential as the device_cert member.
+--invoke       | Yes      | Space separated list (within quotes) of RVI service prefixes that the owner of the credential has the right to invoke.
+--register     | Yes      | Space separated list (within quotes) of RVI service prefixes that the owner of the credential has the right to register for others to call (with the right credential).