Introduction

GCMDll is a library implementing the COSEM/DLMS symmetric security with algorithm AES-GCM-128.

The algorithm, when ciphering, processes a xDLMS APDU and delivers a ciphered-frame. When deciphering, it processes a ciphered-frame and delivers an xDLMS APDU.

The algorithm implements encryption, authentication or both.

It uses the following security elements:

A 16 octets encryption key for encryption of data.

A 16 octets authentication key for authentication of data.

Several key-sets can be distinguished. Unicast keys for secured communication between two peers. Boadcast keys for secure broadcast communication between a client and several servers.

A 8 octets system-title that defines the system (or device) that performs the ciphering. The first 3 octets of the system-title hold the three-letters manufacturer ID. The remainder of the system-title can be a device number.

An unsigned 32 bits frame-counter that must be different for each invocation of the ciphering algorithm.

A security-control value that indicates 1) the ciphering provided: authentication, encryption or both; 2) the kind of ciphering key-set used: unicast or broadcast.

The output of the ciphering process is a ciphered frame with the following format:

If authentication only is selected:

security-control (1 octet), frame-counter (4 octets) plain xDLMS APDU (n octets), authentication tag (12 octets)

If encryption only is selected:

security-control (1 octet), frame-counter (4 octets) ciphered xDLMS APDU (n octets)

If authentication and encryption are selected:

security-control (1 octet), frame-counter(4 octets), ciphered xDLMS APDU (n octets), authentication tag (12 octets)

Copyright © 2012-2017 by i-cube. All Rights Reserved.


API


Types and constants

API ››

The SecurityControl value controls what kind of ciphering is required and what kind of encryption key-set is used.

Possible values for the ciphering are:

AUTHENTICATION_ONLY

ENCRYPTION_ONLY

AUTHENTICATION_AND_ENCRYPTION

Possible values for the encryption key-sets are:

UNICAST_KEYS

BROADCAST_KEYS

The SecurityControl value is determined by ''oring'' these values. Example:

UNICAST_KEYS | ENCRYPTION_ONLY

GCMStatus is a return status that indicates the success/failure of a ciphering or deciphering operation.

int const MaxMessageSize = 256;

struct TGCMStatus

{

bool Ok;

char Message[MaxMessageSize];

};

Ok when true indicates a successful operation, and when false indicates a failure, then Message indicates the reason of the failure.


Cipher and Cipher0

Ciphers a xDLMS plain APDU and delivers a ciphered-frame

void Cipher(unsigned int SecurityControl, void *pPlainAPDU, int nPlainAPDUSize, void *pSystemTitle,

void *pEncryptionKey, void *pAuthenticationKey,

void *pCipheredFrame, unsigned int *pInOutCipheredFrameSize,

TGCMStatus *pGCMStatus

);

Parameters

SecurityControl ( see ),

pPlainAPDU is a generic pointer to the plain xDLMS APDU, of size nPlainAPDUSize,

pSystemTitle is a generic pointer to the 8 octet system-title of the system where the ciphering is performed,

pEncryptionKey is a generic pointer to a 16 octets encryption key,

pAuthenticationKey is a generic pointer to a 16 octets authentication key,

pCipheredFrame is a generic pointer to a buffer that receives the ciphered-frame,

pInOutCipheredFrameSize is a pointer to a unsigned int. On input the value is the maximal size of the buffer available for the ciphered-frame, on output it holds the size of the ciphered-frame,

pGCMStatus is a pointer to a TGCMStatus ( see ) that received success/failure information.

The Cipher routine doesn't have a frame-counter parameter. The required frame-counter value is automatically computed for each routine invocation.

void Cipher0(unsigned int SecurityControl, void *pPlainAPDU, int nPlainAPDUSize, void *pSystemTitle,

void *pEncryptionKey, void *pAuthenticationKey,

void *pCipheredFrame, unsigned int *pInOutCipheredFrameSize,

TGCMStatus *pGCMStatus, unsigned int FrameCounter

);

Parameters

The parameters are identical as in Cipher except that a FrameCounter can be passed (instead of using the automatically generated value).


Decipher

Deciphers a ciphered-frame and delivers a plain xDLMS APDU

bool DeCipher(void *pCipheredFrame, int nCipheredFrameSize, void *pSystemTitle,

void *pEncryptionKey, void *pAuthenticationKey,

void *pPlainAPDU, unsigned int *pInOutPlainAPDUSize, TGCMStatus *pGCMStatus);

Parameters

pCipheredFrame is a generic pointer to the ciphered-frame, of size nCipheredFrameSize,

pSystemTitle is a generic pointer to the 8 octet system-title of the system where the ciphering has been performed (most of the time the remote system),

pEncryptionKey is a generic pointer to a 16 octets encryption key,

pAuthenticationKey is a generic pointer to a 16 octets authentication key,

pPlainAPDU is a generic pointer to a buffer that receives the plain APDU,

pInOutPlainAPDUSize is a pointer to a unsigned int. On input the value is the maximal size of the buffer available for theplain APDU, on output it holds the size of the plain APDU,

pGCMStatus is a pointer to a TGCMStatus ( see ) that received success/failure information.


MakeWrappedKey

Make a wrapped key of a Key using a MasterKey according to the AES-Keywrap algorithm (RFC 3394)

void MakeWrappedKey(void *pKeyToWrap, void *pMasterKey, void *pOutWrappedKey,

unsigned int OutWrappedKeySize);

Parameters

pKeyToWrap is a generic pointer to a 16 octets buffer containing the key to wrap,

pMasterKey is a generic pointer to a 16 octets buffer containing the master key,

pOutWrappedKey is a generic pointer to a 24 octet buffer that will receive the wrapped key,

OutWrappedKeySize is the size of the buffer pointed to by pOutWrappedKey, it must be 24.