cloud_oadr-vtn

Overview

A NodeJS web application providing OpenADR 2.0b services.

Configuration

Files

RSA private key for Kinesis must be installed at pem/private-key.pem.

Environment

Please set the following environment variables:

• NANTUM_URL: URL of Nantum API endpoint to use
• CLIENT_ID / CLIENT_SECRET: Credentials to access Nantum API
• COMPANY: Which company we're associated to
• NODE_ENV: Which environment we're running in. Can be production | development | test.
• ENCRYPT_PASS: The password used to encrypt the RSA private key, as well as LOGGER_PEM
• PORT: The TCP port the webserver should bind to
• REGION: AWS region to use for Kinesis
• INSTANCE_ID: Instance ID to be used by Kinesis-Logger
• LOGGER_PEM: RSA private key contents to be used by Kinesis-Logger
• NO_AWS: Set this true when NODE_ENV is development to be able to run outside an AWS environment

Running locally for development

Environment

At a minimum you will want to set NODE_ENV to development, NO_AWS to true, and configure NANTUM_URL, CLIENT_ID, CLIENT_SECRET, and COMPANY to point to a Nantum instance.

Build

Ensure you have a .npmrc file with an authToken for the @hw and @be private repos. If you get an error E401 it's likely that this is mis-configured.

Run

npm install

to install dependencies.

Running tests

npm run test

Running server

npm run start

Running in Docker for development

Configuration

The following files should be present in the project directory and are referred to by docker-compose.yml

• ssl.crt: VTN certificate file in PEM format. This will be the concatenated result of 3 certificates: 1) VTN cert TEST_RSA_VTN_2003XXXXXXXXX_cert.pem, 2) Root Cert Authority TEST_OpenADR_RSA_RCA0002_Cert.pem, 3) Service Provider TEST_OpenADR_RSA_SPCA0002_Cert.pem. Certificates must be present in that order.
• ssl.key: VTN key file in PEM format. This will come from a file that looks like TEST_RSA_VTN_2003XXXXXXXXX_privkey.pem in the VTN cert bundle.
• clientssl.crt: VEN CA certificate file in PEM format. This will be the concatenated result of 2 certificates from the VEN cert bundle (e.g. TEST_RSA_VEN_2003XXXXXXXXX_certs.zip): 1) Intermediate "MCA" cert TEST_OpenADR_RSA_MCA0002_Cert.pem, 2) Root "RCA" cert TEST_OpenADR_RSA_RCA0002_Cert.pem. Certificates must be present in that order. nginx uses this to validate client certificates.

Build

You will need an authToken for the @hw repo. You should be able to retrieve this by running npm login https://[insert repo url here] and looking in ~/.npmrc or ./.npmrc.

Pass the auth token to ./docker_build.sh like

env NPM_TOKEN=YOURTOKENHERE ./docker_build.sh

Running tests

First follow the Build steps above, then run

./docker_run_tests.sh

Running server

First follow the Build steps above, then run

docker-compose up -d

You can tweak the environment variables in docker-compose.yml.

Client certificate authentication

OpenADR VENs connect using a client TLS certificate. In this Docker-compose configuration, nginx provides:

1) TLS termination: Listens on HTTPS port 443 and proxies to NodeJS plaintext HTTP on port 8080 2) Client certificate chain of trust validation: As mentioned above under Configuration, clientssl.crt contains a Root Certificate and Intermediate Certificate from a trusted CA. These two certificates allow nginx to validate that the VEN-provided client certificate is issued by that trusted CA. 3) HTTP headers to NodeJS: ssl_client_s_dn_cn contains the CN from the VEN client certificate. ssl_client_certificate contains the entire URI-encoded PEM-encoded X.509 client certificate. These headers are consumed by the certificate-parser ExpressJS middleware.

Supported OpenADR VTN functionality

EiRegisterParty service

• oadrCreatePartyRegistration, oadrCancelPartyRegistration, oadrQueryRegistration messages
• simpleHttp transport
• 2.0b profile
• xmpp transport
• 2.0a profile
• ReportOnly VEN feature
• XML Signature VEN feature
• simpleHttp pull model
• simpleHttp push model

EiEvent service

• oadrRequestEvent, oadrCreatedEvent messages

OadrPoll service

• oadrPoll message

EiOpt service

• Not implemented

EiReport service

• oadrRegisterReport, oadrRegisteredReport, oadrCreateReport, oadrCreatedReport, oadrUpdateReport, oadrUpdatedReport messages
• oadrCancelReport, oadrCanceledReport