Using the Nectar API for Production Systems.

reayn3Uncategorized1 Comment on Using the Nectar API for Production Systems.

Prerequisites

  • 35 minutes
  • A valid STS Configuration
  • Linux terminal to run openssl commands

Introduction

In the last post, we had an introduction to the newly released Nectar API and got a demonstration walk through on how one can use to generate valid STSEd2 (STS-6) tokens. This post demonstrated how to do this by filling out the actual STS configuration form in the Configurations section of the Nectar API portal. While using this form from a private computer to add in the elements of an STS configuration is likely secure, on public or shared devices, key loggers or other nefarious programs maliciously installed in the device can capture keystrokes and elements of your STS configuration before the Nectar API client portal encrypts and send the configuration to the cloud.

In this second series of articles on the Nectar API, we will look at the more secure and recommended approach to using the Nectar API to upload STS configurations and use them to generate tokens. A number of these steps will be similar to those used in the earlier post.

Step 1: Create an account

To begin using the Nectar API, first create an account at https://portal.nectar.software/register. You will receive an email to the registered email address for you to confirm registration.

Step 2: Login to Nectar API

Using the created credentials, log into Nectar API and create a new set of credentials at https://portal.nectar.software/credentials. The new set of credentials must contain at minimum the Generate Token Permission. Once the credential is generated, it will have a ref, key and secret. The key and secret will be necessary to make further calls to the Nectar API.

Step 3: Create an STS configuration

Your STS prepaid meter manufacturer or Key Management Center (KMC) manager may provide you with an STS configuration. Or you may provide the manufacturer with an STS configuration and they may provide you with Key Change Tokens (KCTs) to convert their meters to your configuration. Either way, at this point you will require a complete STS configuration for your meter(s) to proceed.

The STS configuration must be composed of the following elements

  • Key Expiry No (KEN)
  • Encryption Algorithm (EA)
  • Decoder Key Generation Algorithm (DKGA)
  • Tariff Index (TI)
  • Key Revision No
  • Vending Key (VK)
  • Supply Group Code (SGC)
  • Key Type (KT)
  • Base Date (BD)
  • Issuer Identification No (IIN)

Please ensure that you have all these required STS configuration elements before proceeding to the next step.

Once obtained, format these configurations into a YAML like document and save it securely on your device with the extension .txt. The following is an example of a valid STS configuration that can be uploaded to the Nectar API portal.

---
name: example_config 
key_expiry_no: 255
encryption_algorithm: sta
token_carrier_type: numeric
decoder_key_generation_algorithm: 04
tariff_index: 01
key_revision_no: 1
vending_key: 0123456789abcdef
supply_group_code: 123456
key_type: 3
base_date: 2035
issuer_identification_no: 600727

Please take note of the following when creating this STS configuration.

  1. The name be any desired STS config name. The Nectar API does not require this it to be unique.
  2. The key_expiry_number can be any integer between 0-255.
  3. The encryption_algorithm must be one of the following values sta, dea or misty .
  4. The token_carrier_type must always be set to numeric.
  5. The decoder_key_generation_algorithm must be one of the following values 01, 02, 03 or 04.
  6. The tariff_index must be a 2 digit number.
  7. The key_revision_no must be a number between 1 and 9.
  8. The vending_key must be a 16 character hexadecimal string. This must be entered in big endian.
  9. The supply_group_code must be a 6 digit number.
  10. The key_type must be a number between 0 and 3.
  11. The base_date must be one of the following values 1993, 2014or 2035.
  12. The issuer_identification_no can either be 600727 or 0000.

If any of these configurations is unclear or not provided, please review the technical specification IEC 62055-41:2018 or reach out to your STS prepaid meter or KMC manager to provide these details.

Step 4: Create an AES symmetric Key and Initialization Vector

A 128 bit AES key and initialization vector (IV) will be required to encrypt your STS configuration. Please use the following command to generate the symmetric key and IV.

echo -n -e 1234567812345678 > iv.txt
echo -n -e "v8y/B?E(H+MbQeTh" > sym.txt

Step 5: Encrypt your STS configuration

You can now use the following commands to encrypt your STS configuration and convert it to base64.

# Convert the sym and IV to hex 
xxd -p -l 16 <<< cat iv.txt # outputs 31323334353637383132333435363738 
xxd -p -l 16 <<< cat sym.txt # outputs 7638792f423f4528482b4d6251655468 

# Encrypt your STS config using the IV and symmetric key  
openssl enc -aes-128-cbc -in sts_config.yml -out encrypted_sts_config_no_iv.bin -K  7638792f423f4528482b4d6251655468 -iv 31323334353637383132333435363738 

# Concatentate the IV and encrypted STS config output 
cp iv.txt encrypted_sts_config_with_iv.bin 
cat encrypted_sts_config_no_iv.bin >> encrypted_sts_config_with_iv.bin 

# base64 the resultant encrypted IV and STS config 
cat encrypted_sts_config_with_iv.bin | base64 > encrypted_sts_config_with_iv_base64.txt

Step 6: Generate an encrypted STS config digest

A message digest of the STS config has to be generated using SHA-256. The hashed message digest then has to be encrypted with your private key. This private key’s, public key pair must already have been uploaded into the Nectar portal. Public keys can be managed using the Public Keys page. The PKI key pair are 4096 bit RSA Keys. The output of the SHA-256 must then be base64 encoded.

The following commands can be used to generate aSHA-256 hash of the STS configuration file and encrypt the configuration file using an RSA private key.

# Generate RSA private key
openssl genrsa -out key.pem 4096 

# Extract the public key
openssl rsa -in key.pem -pubout > public.pub 

# Generate SHA256 digest and sign encrypting it with your private key
cat sts_config.yml | openssl dgst -binary -sha256 | openssl rsautl -sign -inkey key.pem -in - -out - | openssl base64 > encrypted_digest.txt

The public key generated in this step must be uploaded to http://portal.nectar.co.ke/public-keys before next steps. Please note that your need just one set of public-private keys to use the Nectar API. Therefore, when uploading multiple STS configurations, just one PKI pair is required. You can however create multiple, if desired, or if a specific PKI pair is compromised.

Step 7: Encrypt your STS configuration

Any 128 bit AES Key symmetric key can be used to encrypt an STS configuration. An example is v8y/B?E(H+MbQeTh. This symmetric key must be encrypted using Nectar’s Public Key available here.

The following commands can be used to encrypt the symmetric key using Nectar’s public key.

# Encrypt symmetric key using Nectar public key
openssl rsautl -encrypt -pubin -inkey nectar_public.pub -in sym.txt -out encrypted_symmetric.bin

# Convert to base64 encoding
base64 encrypted_symmetric.bin > encrypted_symmetric.txt

Step 8: Upload your STS configuration to the Nectar API portal

At this point, you should have 3 files:

  • An encrypted STS configuration
  • A signed STS configuration digest
  • An encrypted symmetric key

Please review the previous steps to ensure that you have these 3 files before proceeding to next steps. You can now navigate to the configurations page at https://portal.nectar.software/configurations and select the first tab titled Option 1: Upload STS Configuration (Recommended). Upload these three files to the various sections in this form and save. The encrypted files are uploaded to the Nectar API portal and decrypted using your public key and Nectar’s private key and stored in a virtual cloud HSM.

Step 10: Generate Tokens

With a successfully uploaded STS configuration, you are now ready to begin generating prepaid STS tokens using the Nectar API.

There are a number of options to generate tokens using the Nectar API. These are

  1. Use a Java/PHP Nectar API SDK. You can view all Nectar API SDKs at Java, Python, PHP
  2. Make REST requests to the Nectar API at https://api.portal.nectar.software. Refer to the documentation at https://portal.nectar.software/docs for more details.
  3. Through the Nectar API portal itself using the Simulators page at https://portal.nectar.software/simulators and selecting the Token Generator option.

While option 3 above is the fastest, for purposes of this guide, we will use a Nectar API SDK (Option 1) to show how requests to the Nectar API can be integrated into any existing code base. We will use Java.

First modify your build.gradle file to include the Nectar API SDK

implementation group: 'software.nectar.java', name: 'nectar-java-sdk', version: '0.9.2-alpha

Below is an example of token generation code using the Nectar API Java SDK

import software.nectar.java.models.*;
import java.time.Instant;

public class NectarTest {

    // These can be obtained from your credentials page
    // https://portal.nectar.software/credentials
    private final String KEY = "a0...38453";
    private final String SECRET = "cf....fd7a";

    private Nectar nectar = new Nectar(KEY, SECRET);

    public static void main(String[] args) {
        try {
            Instant generationTime = Instant.parse("2018-05-16T07:29:00.00Z");
            int wmFactor = 10, randomNo = 5;
            boolean isStid = false, debug = false;
            String drn = "47500150231", configRef = "cbf4...c846c"; // config ref is an STS config as uploaded on https://portal.nectar.software/configurations

            Token generatedToken = nectar.getTokenFactory()
                    .generateSetWaterMeterFactorToken(generationTime, wmFactor, randomNo, isStid, drn, configRef, debug);
        System.out.println(String.format("Generate Token\n====================\n%s\n", generatedToken));
   
    }
}

This generates the following output

4:04:34 PM: Executing task 'NectarTest.main()'...

> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes

> Task :NectarTest.main()
Response Code : 200
Generate Token
====================
Token { ref: 8e886a29-3766-40a9-9bae-1543e465e355, token_no: 24260829498939505863, user_ref: 49bc59e5-b261-423d-9600-fd479a31aca5,token_type: SetWaterMeterFactor_27, meter_no: 47500150231, created_at: 2021-07-22T13:04:38.386491Z }

Please note that to generate tokens, you will need to procure credits using the ‘Buy’ button on the left of the Nectar API portal. However, if your payment mode is unsupported (or you would like a few test credits :)), please reach out with your request to info@nectar.software.

That’s all folks!

One thought on “Using the Nectar API for Production Systems.”

Comments are closed.