1 of 5

Connect an OCPI/OCN Party to a Node

Overview

The most common use case of the Open Charging Network describes an eMobility Service Provider (eMSP) or Charge Point Operator (CPO) connecting their backend service to an OCN Node. An OCN node provides an entry point into the system, so a party must connect to an OCN node in order to participate in the network.

Follow these steps in order to successfully connect your own backend service.

*Note that not only MSPs and CPOs can use the Open Charging Network, but these are the most common roles.

Access the full OCN technical documentation here

1. Make your backend service OCN-ready

In order for your backend service to be OCN-ready, it must:

Implement the OCPI 2.2 API, the shared communication protocol for the OCN
Implement the OCN Notary in order to sign and verify OCN messages

Access the full OCN technical documentation here.

1. Implement the OCPI 2.2 API

The OCPI protocol is the common communication protocol for the OCN. Each OCN node implements the OCPI 2.2 API (see, for example, the Kotlin implementation of the OCPI 2.2 API for the OCN node here), and every backend-service that communicates with an OCN node must also implement the OCPI 2.2 API.

Using the OCN Bridge

Using the OCN Bridge is an alternative to implementing the full OCPI 2.2 API in your backend service. The OCN Bridge provides an OCPI interface using pluggable backend APIs. You can instantiate an instance of the Bridge, which will proxy your requests and responses with other OCN parties.

In addition to the OCPI 2.2 implementation, the OCN Bridge also provides services to interact with an OCN node (i.e. register with a node, get connection status to a node) and the OCN Registry.

Examples:

public async getNodeInfo(nodeURL: string): Promise<INodeInfo> {
    const res = await fetch(new URL("/ocn/registry/node-info", nodeURL).href)
    return res.json()
}

You can view documentation on how to to implement the OCN Bridge here.

The OCN Bridge simplifies the implementation of the OCPI interface, but it is not required to use in your backend service. Note that the OCN Bridge can only be implemented in JavaScript environments.

2. Implement the OCN Notary

The OCN Notary is a package that enables the verification of OCN signature, which are used to sign and verify OCN requests using public/private key-pairs.

OCN Signatures

Taking a cue from the blockchain community, we have developed a message signing and verifying system for the Open Charging Network.

Under the hood it uses the Elliptic Curve Digital Signature Algorithm (ECDSA) as implemented by Ethereum. The signature itself holds a JSON Object containing all the necessary data for the recipient to verify the data it is receiving.

Not only do requests need to be signed, but responses too.

Signing Requests

For requests, the signature is appended to the outgoing OCPI 2.2 headers:

Authorization: Token 0ea32164-515f-418b-8bef-39f3817ea090

X-Request-ID: 71d62c5b-5017-493e-be00-3f5ad4e34fff

X-Correlation-ID: 9881b6f7-63aa-40d2-b9c2-d6daa69c11fb

OCPI-From-Country-Code: CH OCPI-From-Party-Id:

MSP OCPI-To-Country-Code: CH OCPI-To-Party-Id:

CPO OCN-Signature: eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)...

Signing Responses

For responses, the signature is appended to the outgoing OCPI 2.2 JSON response body:

{

"status_code": 1000,

"data": { "result": "ACCEPTED" },

"timestamp": "2020-03-02T12:48:33.005Z",

"ocn_signature": "eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)..."

}

The idea is that the recipient can use this signature to verify that the message has been signed correctly and has not been modified by an unauthorized party.

What do we mean by unauthorized?

For the OCN to function properly, there are cases where an intermediary (i.e. an OCN node) needs to modify the request/response. Such an example would be the response_url in the JSON body of requests made to the receiver interface of the OCPI commands module. As the recipient does not have access to the response_url defined by the sender, the OCN Node must modify the value. In an OCN signature, this is known as “stashing”. The signature object contains the history of rewrites, with the previous signature being stashed by the party modifying the data. When a recipient then verifies a signature, the rewrites are also verified.

Let’s take a closer look at what the signature actually is:

interface Signature {

val fields: Array val hash: String

val rsv: String

val signatory: String

val rewrites: Array

}

interface Rewrite {

val rewrittenFields: Map<String, Any?>

val hash: String

val rsv: String

val signatory: String

}

The signature itself contains everything needed to verify the most-recent version of the sent data, i.e. by the sender or OCN node depending on whether any values needed to be modified. Provided is a list of jsonpath fields which can be used to recreate the message as signed by the sender, with the original order of values preserved. The values are hashed using keccak-256, as implemented by Ethereum. The resultant hash is actually the message which is signed. The RSV is the signature, produced by ECDSA using an Ethereum wallet’s private key. The signatory refers to the address of the wallet that was used to sign the message.

The list of rewrites contains an object containing the previous hash, rsv and signatory. It also allows the original message to be recreated by storing the fields which have been rewritten. For example, a commands receiver request might have the following rewrite by the OCN node:

1Rewrite( 2 rewrittenFields = mapOf("$['body']['response_url']" to "https://emsp.net/ocpi/2.2/sender/commands/START_SESSION/acfbb8d2-bd49-4837-97e2-d2c38f6bae55"), 3 hash = "0x1ce93f156bc5b3a5c26c5f2499db7bfa2b38c37fd32616fc6487175b86f41eb2", 4 rsv = "0x16e8b9c4e44f4646235fca85a594b5a31057930676d338d111ae985a4f0d9d4214705a0a2ae18c4dfd014581e96eb4625137a937853d4b2d17a0f3a22750f6ac1c", 5 signatory = "0x25e4fca0a0e5107d06d71ed78f687827208d5ff9" 6)

The Signatory

Of course, the signatory of both the OCN Signature and its rewrites should be independently validated. The verification of the signature only tells us that the message was signed by the signatory provided. The signatory itself could be any Ethereum wallet address. The address of both the original sender and their OCN node can be found in the OCN Registry[link to repo].

Now that we know how the signature functions, how do we actually use it? Enter the OCN Notary.

Implementing the OCN Notary

The OCN Notary implements the above Signature and Rewrite interfaces. It can deserialize an incoming OCN Signature and verify its contents. It can be used to sign an OCPI request, and likewise to stash/rewrite values in a request.

Currently the Notary library is available as an NPM package and as a Maven package for languages targeting the JVM. See the OCN Notary repository to find more information for each package.

OCN Network v1.0 Open API 3.0 Specs

You can find the API specification document in the OCN Node repository, here: Open API 3.0 specs

Using this specification, it is possible to generate client code and test implementations. For more information, see https://swagger.io/docs/specification/about/.

Note that this document was generated using unmodified source code in the master branch. As such, certain features of the specification format might be missing, such as examples for HTTP requests and responses.

2. Select an OCN Node and register in OCN Registry

In order to connect a service to the OCN, you must choose which OCN node you want to connect to, and know the node's public wallet address. You will then request a registration token (Token_A) from your selected node.

Access the full OCN technical documentation here.

1. Select a node

In order to connect a service to the Open Charging Network, you must decide which OCN Node you want to connect to.

Test Network

To view public nodes available on the public test network and their wallet address, see "Develop on the Test Network".

Production Network

To view public nodes available on the public test network and their wallet address, see "Develop on the Production Network".

2. Request a Token

Once you select a node operator that you want to connect to, you must:

Know the OCN Identity (wallet address) of that OCN Node Operator (from Step One above).
Request a registration token (TOKEN_A in OCPI terms). Note that this token is only temporary and will become invalid once the registration is complete.

3. Enter Node details in OCN Registry

After you have the public address of your public node and your registration token, you are now ready to create / update your OCN Identity on the OCN Registry. Follow the steps provided here: Create and manage an OCN Identity

3. Manage your Whitelist and Blacklist

The Open Charging Network allows you to exchange OCPI messages with anybody on the network with just one single OCPI connection, regardless of the OCN Node that you or your counterpart are connected to.

There are some cases in which you want to restrict the list of parties that can communicate with you. For this, the OCN Node provides you with a white- and blacklisting module, called OCN Rules.

Note: This service is an optional feature that needs to be enabled in your own OCN Node or by your OCN Node Operator.

Example: add party to blacklist

POST to URL: https://node.ocn.org/ocpi/receiver/2.2/ocnrules/blacklist

    {
        "country_code": "DE",
        "party_id": "ABC",
        "modules": ["cdrs", "locations"]
    }

You can find a documentation of how you can use this service on the HTTP API Documentation under OcnRules module.
See the source code for the OCN node Rules service here.

Access the full OCN technical documentation here.

4. Connect your service to an OCN Node

If you have followed the previous steps in this tutorial you should now have the following things ready for making your connection to the Open Charging Network:

(TOKEN_A in OCPI Terms)

Follow the steps listed below to connect to your OCN Node

Access the full OCN technical documentation .

1. Get the Public URL of your selected OCN node from the OCN Registry

There are three methods of interacting with the OCN Registry:

Using the CLI

ocn-registry get-node 0xEada1b2521115e07578DBD9595B52359E9900104

Where 0xEada1b2521115e07578DBD9595B52359E9900104 is the operator's public address.

Using the Typescript Library

The Public URL could look something like this: https://test-node.emobilify.com

Once connected to the registry, you can use the getNode method to return the operator's public URL:

Using the Java Library

2. Get OCN Node versions and endpoints

We will first send a GET request to the OCN Node’s versions endpoint, using the TOKEN_A we received from the faucet. Note that curl requests can be imported into e.g. Postman or Insomnia if desired.

Do the same for this endpoint:

You should see a long list of OCPI version 2.2 endpoints implemented by the OCN Node. You will want to save these endpoints for future reference in your application’s database.

For now though, we just need one endpoint. Find the endpoint URL for the module identifier “credentials”. This will be the one we use to connect to the node:

3. Ensure OCN Node can access our versions and endpoints

The OCN Node needs to know where to contact us in case there is a message from another party that needs to be routed to us. It can also help to filter requests, in the case that we have not implemented a specific OCPI module that another party is requesting from us.

This will create an authorization token that the OCN Node should use to access our own endpoints. It is logged on start. Be sure to make a note of the authorization token as we will need it later.

Note also the PUBLIC_IP. We want the OCN Node to be able to access these endpoints from the outside, so we should make sure that the server is reachable via the public IP we set.

4. Credentials handshake

Now we are ready to connect to the OCN Node.

The credentials request is detailed below. Make sure to replace the variables TOKEN_A, TOKEN_B and PUBLIC_IP, PARTY_ID and COUNTRY_CODE where described:

TOKEN_A should match the one generated for you by the faucet
TOKEN_B should match the authorization token that you have created
PUBLIC_IP should point to your publicly accessible web service

If the request is successful, you should see a response with OCPI status code 1000 and the OCN Node’s credentials returned in the body.

Now that we have connected to the Open Charging Network we can make use of OCPI to find point of interest data, issue remote commands at charge points and authorize RFID cards of any other OCPI party that is connected to the network.

4. Connect your service to an OCN Node

If you have followed the previous steps in this tutorial you should now have the following things ready for making your connection to the Open Charging Network:

(TOKEN_A in OCPI Terms)

Follow the steps listed below to connect to your OCN Node

Access the full OCN technical documentation .

1. Get the Public URL of your selected OCN node from the OCN Registry

There are three methods of interacting with the OCN Registry:

Using the CLI

If you are using the on GitHub, you can check the Public URL of your selected OCN Node by doing this:

ocn-registry get-node 0xEada1b2521115e07578DBD9595B52359E9900104

Where 0xEada1b2521115e07578DBD9595B52359E9900104 is the operator's public address.

Using the Typescript Library

You can find documentation on how to install and use the library .

The Public URL could look something like this: https://test-node.emobilify.com

Please visit the for further details about this step.

Once connected to the registry, you can use the getNode method to return the operator's public URL:

     /**
     * Get a registry node listing for a given operator.
     * @param operator Ethereum address of the operator.
     * @returns the domain name/url if listing exists.
     */
    public async getNode(operator: string): Promise<string | undefined> {
        this.verifyAddress(operator)
        const node = await this.registry.getNode(operator)
        return node || undefined
    }

Using the Java Library

Use the documentation provided to connect to the OCN Registry using the Java library.

2. Get OCN Node versions and endpoints

curl https://test-node.emobilify.com/ocpi/versions -H 'Authorization: Token {{TOKEN_A}}'

You should see a JSON response with OCPI status code 1000. The response data will tell you that version 2.2 can be found at .

Do the same for this endpoint:

curl https://test-node.emobilify.com/ocpi/2.2 -H 'Authorization: Token {{TOKEN_A}}'

You should see a long list of OCPI version 2.2 endpoints implemented by the OCN Node. You will want to save these endpoints for future reference in your application’s database.

For now though, we just need one endpoint. Find the endpoint URL for the module identifier “credentials”. This will be the one we use to connect to the node:

{
  "identifier": "credentials",
  "role": "SENDER",
  "url": "https://test-node.emobilify.com/ocpi/2.2/credentials"
}

3. Ensure OCN Node can access our versions and endpoints

During the credentials handshake, the OCN Node will attempt to request our own versions and endpoints, just as we did before in

If you have not already done so, we can spin up a quick server and execite a node script that will display our versions and endpoints as follows (note: requires , and ):

const express = require("express")
const uuid = require("uuid")

const app = express()

const PUBLIC_URL = "https://service.msp.com"
const TOKEN_B = uuid.v4()
console.log("Auth TOKEN_B = " + TOKEN_B)


const authorize = (req, res, next) => {
	if (req.headers.authorization !== `Token ${TOKEN_B}`) {
		return res.status(401).send({
			status_code: 2001,
			status_message: "Unauthorized",
			timestamp: new Date()
		})
	}
	next()
} 


app.get("/ocpi/versions", authorize, async (_, res) => {
	res.send({
		status_code: 1000,
		data: {
			versions: [{
				version: "2.2",
				url: `${PUBLIC_URL}/ocpi/2.2`
			}]
		},
		timestamp: new Date()
	})
})


app.get("/ocpi/2.2", authorize, async (_, res) => {
	res.send({
		status_code: 1000,
		data: {
			version: "2.2",
			endpoints: [
				/* {
					identifier: "locations",
					role: "RECEIVER",
					url: `${PUBLIC_URL}/ocpi/2.2/receiver/locations`
				} */
			]
		},
		timestamp: new Date()
	})
})


app.listen(3000, () => { console.log("Started on port 3000") })

Note also the PUBLIC_IP. We want the OCN Node to be able to access these endpoints from the outside, so we should make sure that the server is reachable via the public IP we set.

4. Credentials handshake

Now we are ready to connect to the OCN Node.

The credentials request is detailed below. Make sure to replace the variables TOKEN_A, TOKEN_B and PUBLIC_IP, PARTY_ID and COUNTRY_CODE where described:

TOKEN_A should match the one generated for you by the faucet
TOKEN_B should match the authorization token that you have created
PUBLIC_IP should point to your publicly accessible web service
PARTY_ID and COUNTRY_CODE refer to the same OCPI credentials that you used

curl https://test-node.emobilify.com/ocpi/2.2/credentials \
  -H 'Authorization: Token {{TOKEN_A}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "token": "{{TOKEN_B}}",
    "url": "{{PUBLIC_IP}}/ocpi/versions",
    "roles": [{
      "party_id": "{{PARTY_ID}",
      "country_code": "{{COUNTRY_CODE}}",
      "role": "EMSP",
      "business_details": {
        "name": "Tutorial MSP"
      }
    }]
  }'

If the request is successful, you should see a response with OCPI status code 1000 and the OCN Node’s credentials returned in the body.

1. Make your backend service OCN-ready

In order for your backend service to be OCN-ready, it must:

Implement the OCPI 2.2 API, the shared communication protocol for the OCN
Implement the OCN Notary in order to sign and verify OCN messages

Access the full OCN technical documentation here.

1. Implement the OCPI 2.2 API

Using the OCN Bridge

In addition to the OCPI 2.2 implementation, the OCN Bridge also provides services to interact with an OCN node (i.e. register with a node, get connection status to a node) and the OCN Registry.

Examples:

public async getNodeInfo(nodeURL: string): Promise<INodeInfo> {
    const res = await fetch(new URL("/ocn/registry/node-info", nodeURL).href)
    return res.json()
}

You can view documentation on how to to implement the OCN Bridge here.

The OCN Bridge simplifies the implementation of the OCPI interface, but it is not required to use in your backend service. Note that the OCN Bridge can only be implemented in JavaScript environments.

2. Implement the OCN Notary

The OCN Notary is a package that enables the verification of OCN signature, which are used to sign and verify OCN requests using public/private key-pairs.

OCN Signatures

Taking a cue from the blockchain community, we have developed a message signing and verifying system for the Open Charging Network.

Not only do requests need to be signed, but responses too.

Signing Requests

For requests, the signature is appended to the outgoing OCPI 2.2 headers:

Authorization: Token 0ea32164-515f-418b-8bef-39f3817ea090

X-Request-ID: 71d62c5b-5017-493e-be00-3f5ad4e34fff

X-Correlation-ID: 9881b6f7-63aa-40d2-b9c2-d6daa69c11fb

OCPI-From-Country-Code: CH OCPI-From-Party-Id:

MSP OCPI-To-Country-Code: CH OCPI-To-Party-Id:

CPO OCN-Signature: eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)...

Signing Responses

For responses, the signature is appended to the outgoing OCPI 2.2 JSON response body:

{

"status_code": 1000,

"data": { "result": "ACCEPTED" },

"timestamp": "2020-03-02T12:48:33.005Z",

"ocn_signature": "eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4L (truncated)..."

}

The idea is that the recipient can use this signature to verify that the message has been signed correctly and has not been modified by an unauthorized party.

What do we mean by unauthorized?

Let’s take a closer look at what the signature actually is:

interface Signature {

val fields: Array val hash: String

val rsv: String

val signatory: String

val rewrites: Array

}

interface Rewrite {

val rewrittenFields: Map<String, Any?>

val hash: String

val rsv: String

val signatory: String

}

The Signatory

Now that we know how the signature functions, how do we actually use it? Enter the OCN Notary.

Implementing the OCN Notary

Currently the Notary library is available as an NPM package and as a Maven package for languages targeting the JVM. See the OCN Notary repository to find more information for each package.

OCN Network v1.0 Open API 3.0 Specs

You can find the API specification document in the OCN Node repository, here: Open API 3.0 specs

Using this specification, it is possible to generate client code and test implementations. For more information, see https://swagger.io/docs/specification/about/.