This document is licensed under Creative Commons Attribution-ShareAlike 4.0 International.

CREATING RVI CERTIFICATES

This document describes how to generate the necessary certificates, keys and credentials needed for RVI Core. The example certificates are used in (rvi_protocol.md)[rvi_protocol.md].

STANDARDS USED

[1] JSON Web Token RFC7519- JWT (link)[https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-32]
[2] base64url - (link)[https://en.wikipedia.org/wiki/Base64)
[3] Transport Layer Security (TLS) - (link)[https://en.wikipedia.org/wiki/Transport_Layer_Security]
[4] X.509 Certificates - (link)[https://en.wikipedia.org/wiki/X.509]

For all examples below the following certificates are used:

Sample root certificate

The self signed root certificate used in the examples throughout this document was generated using the following commands:

# Create root key pair
openssl genrsa -out insecure_root_key.pem 1024

# Create a self-signed root CA certificate, signed by the root key created above
openssl req -x509 -new -nodes -key insecure_root_key.pem -days 365 -out insecure
_root_cert.crt

The content of the sample insecure_root_key.pem private key file, which has no password protection, is:

The root key above is checked in as priv/keys/insecure_root_key.pem.

The content of the sample insecure_root_cert.crt file is:

The root certificate above is checked in as priv/certificates/insecure_root_cert.crt.

DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION!
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:

# Create the device key. In production, increase the bit size to 4096+
openssl genrsa -out insecure_device_key.pem 1024

# Create a certificate signing request
openssl req -new -key insecure_device_key.pem -out insecure_device_cert.csr

# Sign the signing request and create the insecure_device_cert.crt file
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 insecure_device_key.pem private key file, which has no password protection, is:

The content of the sample insecure_device_cert.crt file is:

These files are checked into priv/certificates and priv/keys.

DO NOT USE THE KEYS AND CERTIFICATES ABOVE IN PRODUCTION!
ANY PRODUCTION KEYS SHOULD BE GENERATED BY THE ORGANIZATION AND BE 4096 BITS LONG.

RVI credentials format

A credential is a JWT-encoded JSON structure, signed by the root X.509 certificate's private key, describing the rights that the sender has. A received RVI credential is validated as follows.

Receive remote party's X.509 device certificate
The TLS handshake process will exchange the X.509 certificates setup in the previous chapter.
Validate remote party's X.509 device certificate
The received device X.509 certificate has its signature validated by the root X.509 certificate that is pre-provisioned in all RVI nodes.
The receiver now knows that the remote RVI node has an identiy generated by a trusted provsioning server using the private root key.
Receive one or more RVI credentials
Each credential is encoded as JWT, signed by the root X.509 certificate.
Validate each RVI credential signature
The root X.509 certificate is used to validate the signature of each received RVI credential.
A successful validation proves that the certificate was generated by a trusted provisioning server using the private root key.
Validate the credential-embedded X.509 device certificate
Each received RVI credential will have its embedded device X.509 certificate compared with the device X.509 certificate received in step 1 above.
A match proves that the certificate was generated by a trusted provisioning server explictly for the RVI node at the remote end.

An RVI credential has the following format in its native JSON state:

{
    "create_timestamp": 1439925416,
    "right_to_invoke": [
        "jlr.com/vin/"
    ],
    "right_to_receive": [
        "jlr.com/backend/sota"
    ],
    "id": "insecure_cert",
    "iss": "jaguarlandrover.com",
    "device_cert": "",
    "validity": {
        "start": 1420099200,
        "stop": 1925020799
    }
}

The members are as follows:

Member	Description
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_receive	A list of services that the sender has the right to to receive remote invocations for from remote nodes.
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.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:

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/' \
                         --receive='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.
--receive	Yes	Space separated list (within quotes) of RVI service prefixes that the owner of the credential has the right to have invoked by other nodes (with the right credential).
--start	No	The Unix timestamps when the credential becomes active.
--stop	No	The Unix timestamps when the credential becomes inactive.

The generated insecure_credential.json and insecure_credential.jwt are checked into priv/credentials.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rvi_certificates.md

rvi_certificates.md

CREATING RVI CERTIFICATES

STANDARDS USED

Sample root certificate

Sample device certificate

RVI credentials format

Generating RVI credentials

Files

rvi_certificates.md

Latest commit

History

rvi_certificates.md

File metadata and controls

CREATING RVI CERTIFICATES

STANDARDS USED

Sample root certificate

Sample device certificate

RVI credentials format

Generating RVI credentials