@smartdcc/dccboxed-keystore

DCC Boxed (Local) Key Store

This repo holds (1) a JSON database of certificates and private keys for use with DCC Boxed and (2) a TypeScript library for accessing/updating the database from a DCC Boxed instance.

The provided database is preloaded with the ZAZ1 remote party credentials to enable a user to sign/validate DUIS XML signatures. However, specific device certificates need to be fetched from the SMKI service on the DCC Boxed instance. Thus, part of the TypeScript library includes code that can query the SMKI service for a device certificate.

Note: ZAZ1 is a self contained PKI for UK smart meter devices used for testing and validation purposes. The ZAZ1 PKI is used by DCC Boxed and any smart energy devices attached to it.

Usage

Requirements

Developed and tested against node 16. Install from npm:

npm i @smartdcc/dccboxed-keystore

Standalone JSON Database

If your use case is to access the key material for a DCC Boxed in a non JavaScript application then a it is possible to generate an JSON file with the certificates and keys in. For example, the keystore.json file included in this project can be used freely in other projects.

Alternatively, if you have access to a DCC Boxed instance then this file can be generated using the following command (along with and additional certificates that can be included):

npm run build:db <boxed ip address> <outputfile.json> [<additional serials in hex>...]

The above command runs a script which:

• downloads the org-certs.zip file from DCC Boxed and converts the contained key material into a format needed by the database.
• The additional serials in hex allows for certificates that are stored in the SMKI service but not in org-certs.zip file to be fetched and added to the database, e.g. the ACB digital signature is one such certificate that is useful to have.

The format of the JSON database file is defined in schema.json.

Typical Use Case

The typical use case of this library is to provide a complete wraparound all needed key material for using DCC Boxed. Thus, it exposes the BoxedKeyStore class. This class provides:

• Local cache (stored in a json db file of the same format described above)
• Backed by readonly access to the keystore.json
• Will search DCC Boxed SMKI for devices certificates if not found in either 1. or 2. and add them to its local cache.

Currently in step 3 it will only search for device certificates as it is assumes that organisation certificates will not change in normal use so will be provided in keystore.json.

An example of its usage would be as follows:

import { BoxedKeyStore, KeyUsage } from '@smartdcc/dccboxed-keystore'

const boxedIpAddress: string = '1.2.3.4'
const keyStore = await BoxedKeyStore.new(boxedIpAddress)

console.log(
  await keyStore.query({
    eui: '90B3D51F30010000',
    keyUsage: KeyUsage.digitalSignature,
    lookup: 'certificate',
    role: 2
  })
)

/* delete any temporary cache files, keyStore should not be used again after this. */
await keyStore.cleanup()

This could output the following (where X509Certificate is a class provided by NodeJS's crypto library):

[
  {
    eui: EUI { eui: '90b3d51f30010000' },
    keyUsage: [ 0 ],
    serial: 98403031005530424935033843217390525231n,
    role: 2,
    certificate: X509Certificate {
      subject: 'CN=GITTESTSUPPLIER\nOU=02\nx500UniqueIdentifier=\x90³Õ\\1F0\\01\\00\\00',
      subjectAltName: undefined,
      issuer: 'OU=07\nCN=Z1',
...snip...
      serialNumber: '4A07BC01D9253B51FAF01F7EC7DA5B2F'
    },
    name: 'Z1b-supplier-ds'
  },
  {
    eui: EUI { eui: '90b3d51f30010000' },
    keyUsage: [ 0 ],
    serial: 105986833131214866166891566273223584671n,
    role: 2,
    certificate: X509Certificate {
      subject: 'CN=GITTESTSUPPLIER\nOU=02\nx500UniqueIdentifier=\x90³Õ\\1F0\\01\\00\\00',
      subjectAltName: undefined,
      issuer: 'OU=07\nCN=Z1',
...snip...
      serialNumber: '4FBC525201A1D7586C1BC1C4734DEB9F'
    },
    name: 'Z1-supplier-ds'
  }
]

Alternatively, looking up the corresponding private keys would be as follows:

console.log(
  await keyStore.query({
    eui: '90B3D51F30010000',
    keyUsage: KeyUsage.digitalSignature,
    lookup: 'privateKey',
    role: 2
  })
)

This could output the following (where PrivateKeyObject is a class provided by NodeJS's crypto library):

[
  {
    eui: EUI { eui: '90b3d51f30010000' },
    keyUsage: [ 0 ],
    serial: 98403031005530424935033843217390525231n,
    role: 2,
    privateKey: PrivateKeyObject { [Symbol(kKeyType)]: 'private' },
    name: 'Z1b-supplier-ds'
  },
  {
    eui: EUI { eui: '90b3d51f30010000' },
    keyUsage: [ 0 ],
    serial: 105986833131214866166891566273223584671n,
    role: 2,
    privateKey: PrivateKeyObject { [Symbol(kKeyType)]: 'private' },
    name: 'Z1-supplier-ds'
  }
]

Its just as easy to lookup a device certificate (which are not stored in keystore.json so is queried from DCC Boxed SMKI web service, if it exists):

console.log(
  await keyStore.query({
    eui: '00-db-12-34-56-78-90-a4',
    keyUsage: KeyUsage.keyAgreement,
    lookup: 'certificate',
  })
)

Alternatively, it is possible to also query by serial number:

console.log(
  await keyStore.query({
    serial: BigInt('105986833131214866166891566273223584671'),
    lookup: 'certificate',
  })
)

If persistence of the local cache is required between program runs then the class should be instantiated as follows:

const keyStore = await BoxedKeyStore.new(boxedIpAddress, localCacheFile)

If the localCacheFile is omitted, a temporary file is created in the system temp folder.

Using Headers with BoxedKeyStore

The BoxedKeyStore can be configured with custom headers for SMKI requests:

import { BoxedKeyStore, KeyUsage } from '@smartdcc/dccboxed-keystore'

// Headers can be static values, sync functions, or async functions
const headers = {
  'X-Authentication': 'Bearer token123',
  'X-Timestamp': () => Date.now().toString(),
  'X-Dynamic-Token': async () => await fetchToken()
}

const keyStore = await BoxedKeyStore.new('1.2.3.4', undefined, undefined, headers)

// Headers will be automatically used for any SMKI queries
const result = await keyStore.query({
  eui: '00-db-12-34-56-78-90-a4',
  keyUsage: KeyUsage.keyAgreement,
  lookup: 'certificate'
})

await keyStore.cleanup()

Advanced Usage

Certificate Metadata

In addition to the key store features described above, two utility functions are provided to parse and extract meta data from smart metering certificates. See buildOrgCertificateMetadata and buildDeviceCertificateMetadata functions in certificateMetadata.ts.

To better understand the difference between Organisation and Device certificates please consult the Smart Energy Code and see Appendix A and Appendix B.

Query Certificates

Client side code to query the DCC Boxed SMKI service is located in certificateSearch.ts. It provides the ability to use both the certificate search and certificate retrieve API (as supported by DCC Boxed). For information about these API's, please consult the Smart Energy Code and see Appendix M.

Store Internals

The underlying datastore class is provided as KeyStoreDB, which is a wrapper around the node-json-db package. This defines both the query and push operations used by BoxedKeyStore.

Contributing

Contributions are welcome!

When submitting a pull request, please ensure:

• Each PR is concise and provides only one feature/bug fix.
• Unit test are provided to cover feature. The project uses jest. To test, run npm run test:cov to view code coverage metrics.
• Bugfixes are reference the GitHub issue.
• If appropriate, update documentation.
• Before committing, run npm run lint and npm run prettier-check.

If you are planning a new non-trivial feature, please first raise a GitHub issue to discuss it to before investing your time to avoid disappointment.

Any contributions will be expected to be licensable under GPLv3.

Other Info

Copyright 2022, Smart DCC Limited, All rights reserved. Project is licensed under GPLv3.