@smartdcc/gbcs-parser
v0.3.2
Published
GBCS parser based on henrygiraldo.github.io
Downloads
128
Maintainers
Readme
GBCS Parser
Tool based on HenryGiraldo/gbcs-parser-js, which is a super useful browser based GBCS parser. It has been uplifted to use TypeScript and output JSON instead of performing DOM manipulations so it can be used in NodeJS. As a result, the use of the cryptographic functions in the original version have been swapped over for crypto API provided by NodeJS Crypto API.
The parser is aimed at being used with DCC Boxed, so does not need full
coverage of GBCS. Tht is, it is intended to be used from service user
perspective which needs to parse the GBCS payloads made available through DUIS.
As such, support for GBT (i.e. segmented messages) has been removed. It has been
lightly tested against RTDS 4.5.0
(Reference Test Data Set). Further, the
parser has been tweaked to provide more slightly more structured parsed data as
it returns JSON instead of filling a HTML table. Please see the
example below to show how a message is parsed and typical
output.
Additional features have been added, which include:
Usage
Please note, developed against node 16
and makes use of its crypto
api.
Install from npm
:
npm i @smartdcc/gbcs-parser
The library exposes a few high-level functions that are intended to be used externally. This includes:
parseGbcsMessage
minimizeMessage
signGroupingHeader
utrn
In addition, to use the parseGbcsMessage
and signGroupingHeader
functions a
key store needs to be provided. The makes available either digital signature or
key agreement certificates (as defined by GBCS). The key store is a simple
asynchronous callback which the user can implement (e.g. it could query
certificates from a DCC Boxed service). In the examples below, the
dccboxed-keystore project is used.
Setup Key Store for DCC Boxed
The below code shims the interface provided by dccboxed-keystore into the correct format for this project. It is intended to provide access to default keys installed on DCC Boxed and query its SMKI interface for certificates it does not have (e.g. device certificates). Below code can be extended as needed.
import { KeyObject } from 'node:crypto'
import { BoxedKeyStore, KeyUsage } from '@smartdcc/dccboxed-keystore'
/**
* used to filter certificates/keys that are not needed
*/
function removeNotBoxedEntries<T extends { role?: number; name?: string }>(
prepayment: boolean
): ({ role, name }: T) => boolean {
return ({ role, name }: T) =>
role !== 135 &&
(name === undefined ||
(prepayment && name.match(/^Z1-[a-zA-Z0-9]+PP-/) !== null) ||
(!prepayment &&
name.match(/^Z1-[a-zA-Z0-9]+(?!PP)[a-zA-Z0-9]{2}-/) !== null))
}
const keyStore = await BoxedKeyStore.new(
'1.2.3.4', /* ip address of dcc boxed */
)
/**
* define callback
*/
async function LocalKeyStore(
eui: string | Uint8Array,
type: 'KA' | 'DS',
options: {
privateKey?: boolean
prePayment?: boolean
}
): Promise<KeyObject> {
if (options.privateKey) {
let results = await keyStore.query({
eui,
keyUsage:
type === 'DS' ? KeyUsage.digitalSignature : KeyUsage.keyAgreement,
lookup: 'privateKey',
})
results = (results ?? []).filter(
removeNotBoxedEntries(options.prePayment ?? false)
)
if (results.length === 1) {
return results[0].privateKey
}
} else {
let results = await keyStore.query({
eui,
keyUsage:
type === 'DS' ? KeyUsage.digitalSignature : KeyUsage.keyAgreement,
lookup: 'certificate',
})
results = (results ?? []).filter(
removeNotBoxedEntries(options.prePayment ?? false)
)
if (results.length === 1) {
return results[0].certificate.publicKey
}
}
throw new Error(
`${options.privateKey ? 'private' : 'public'} key ${
options.prePayment ? '(prepayment)' : ''
} not found for ${eui} for ${type}`
)
}
Parse Message
import { parseGbcsMessage, minimizeMessage } from '@smartdcc/gbcs-parser'
import { inspect } from 'node:util'
const parsed = await parseGbcsMessage(
'3QAAAAAAAFURAAAAAN8JAgAAAYKDJi7hCLwzrAD++lU8CJCz1R8wAAACABIAWZCz1R8wAQAAAAABgoMmLUUR2iAmLuEAAAEJBAACAAABAQAACahvMaB+y9JJIHeL',
LocalKeyStore
)
console.log(inspect(minimizeMessage(parsed), { colors: true, depth: 10 }))
The use of minimizeMessage
removed redundant information from the output of
parseGbcsMessage
which is used to keep the state of the parser.
This produces the following:
{
'MAC Header': {
'General Ciphering': { hex: 'DD 00 00 00 00 00 00' },
'Ciphered Service Length': { hex: '55', notes: '85' },
'Security Header': { hex: '11 00 00 00 00' }
},
'Grouping Header': {
'General Signing': { hex: 'DF 09' },
'CRA Flag': { hex: '02', notes: 'Response' },
'Originator Counter': { hex: '00 00 01 82 83 26 2E E1', notes: '1660057693921' },
'Originator System Title': { hex: '08 BC 33 AC 00 FE FA 55 3C' },
'Recipient System Title': { hex: '08 90 B3 D5 1F 30 00 00 02' },
'Date Time': { hex: '00' },
'Other Information Length': {
hex: '12',
notes: '18',
children: {
'Message Code': {
hex: '00 59',
notes: 'ECS52 Read ESME/Comms Hub Firmware Version'
},
'Supplementary Remote Party ID': { hex: '90 B3 D5 1F 30 01 00 00' },
'Supplementary Remote Party Counter': { hex: '00 00 01 82 83 26 2D 45', notes: '1660057693509' }
}
},
'Content Length': { hex: '11', notes: '17' }
},
Payload: {
'DLMS Access Response': {
hex: 'DA 20 26 2E E1 00 00',
children: {
'List of Access Response Data': {
hex: '01',
children: {
'[0] Octet String': { hex: '09 04 00 02 00 00', notes: '00:02:00.00' }
}
},
'List of Access Response Specification': {
hex: '01',
children: {
'[0] Access Response Specification': {
hex: '01',
notes: 'Access Response Get [0]',
children: { 'Data Access Result': { hex: '00', notes: 'Success' } }
}
}
}
}
}
},
Signature: { 'Signature Length': { hex: '00', notes: '0' } },
MAC: { MAC: { hex: '09 A8 6F 31 A0 7E CB D2 49 20 77 8B' } }
}
The interested reader is suggested to compare this with the output of HenryGiraldo/gbcs-parser-js.
Parsing ECS24 - Read ESME Tariff Data
If the message parsed is a ECS24
, there an additional decoder provided
decodeECS24
. This will take the output from the parser (described above) and
construct a Tariff
object. The definition of an ESME tariff is in
@smartdcc/duis-templates
package.
The decodeECS24
function is intended to be used as follows:
const ecs24 = decodeECS24(minimizeMessage(gbcs))
if (ecs24) {
/* valid ecs24 payload found and decoded */
console.log(inspect(ecs24, { colors: true, depth: 10 }))
} else {
/* no valid ecs24 found */
}
Sign Message
The library provides support for signing GBCS pre-commands. The current
implementation allows for either a null or omitted signature in the pre-command,
this is to provide flexibility to be compatible with early versions of
DCC Boxed which deviated from the DUIS standard. The correct interpretation
of DUIS is to require pre-commands to have a null signature, i.e. a null
byte.
To sign a message, use the following:
import { signGroupingHeader } from '@smartdcc/gbcs-parser'
console.log(await signGroupingHeader(
'90-b3-d5-1f-30-01-00-00',
'3wkBAAABgoNAlH0IkLPVHzABAAAIvDOs//76VT0AAgBibNkgQJR9AAUCAAgAAAEAAP8JAwAIAAABAAD/BQMACAAAAQAA/wQBAAgAAAEAAP8CAQAIAAABAAD/BAUWBQIDCQz///////////+AAP8JDAfeDB//FzsKAIAA/wkMB98BAf8AAAoAgAD/DwAAAA==',
LocalKeyStore,
))
This could produce the following:
3wkBAAABgoNAlH0IkLPVHzABAAAIvDOs//76VT0AAgBibNkgQJR9AAUCAAgAAAEAAP8JAwAIAAABAAD/BQMACAAAAQAA/wQBAAgAAAEAAP8CAQAIAAABAAD/BAUWBQIDCQz///////////+AAP8JDAfeDB//FzsKAIAA/wkMB98BAf8AAAoAgAD/DwAAAECKdRM+cYyVimzkVv9VdaEneMRUTTtP8O8e0IPakREPLfqgx4CDHzYGmPSzhQ+3PxIz9v8hD3N4cv73SIv8p9Gx
Generate UTRN
To generate a UTRN, see the following example:
import { utrn } from './src/index'
const token = utrn({
counter: BigInt(0x100000000) /* low 32 bit should be zero */,
lookupKey: LocalKeyStore,
originator: '90B3D51F30010000',
target: 'BC-33-AC-FF-FE-FA-55-3D',
value: 150,
valueClass: 'pennies',
})
console.log(await token)
Which would then output a token of the form 73942983744751930738
.
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, runnpm run test:cov
to view code coverage metrics. - Bugfixes are reference the GitHub issue.
- If appropriate, update documentation.
- Before committing, run
npm run lint
andnpm 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.
Also, copyright for the original work remains with HenryGiraldo/gbcs-parser-js.