Handle external access to data model and access control

Functions and callbacks to handle and restrict external access to the data model and services. More...

Typedefs
typedef MmsDataAccessError(*	WriteAccessHandler) (DataAttribute *dataAttribute, MmsValue *value, ClientConnection connection, void *parameter)
	callback handler to intercept/control client write access to data attributes More...
typedef MmsDataAccessError(*	ReadAccessHandler) (LogicalDevice *ld, LogicalNode *ln, DataObject *dataObject, FunctionalConstraint fc, ClientConnection connection, void *parameter)
	callback handler to control client read access to data attributes More...
typedef bool(*	IedServer_DataSetAccessHandler) (void *parameter, ClientConnection connection, IedServer_DataSetOperation operation, const char *datasetRef)
	Callback that is called when the client is calling a dataset operation (create, delete, read, write, list directory) More...
typedef bool(*	IedServer_DirectoryAccessHandler) (void *parameter, ClientConnection connection, IedServer_DirectoryCategory category, LogicalDevice *logicalDevice)
typedef bool(*	IedServer_ListObjectsAccessHandler) (void *parameter, ClientConnection connection, ACSIClass acsiClass, LogicalDevice *ld, LogicalNode *ln, const char *objectName, const char *subObjectName, FunctionalConstraint fc)
	Callback that is called when a client is invoking a list objects service. More...
typedef bool(*	IedServer_ControlBlockAccessHandler) (void *parameter, ClientConnection connection, ACSIClass acsiClass, LogicalDevice *ld, LogicalNode *ln, const char *objectName, const char *subObjectName, IedServer_ControlBlockAccessType accessType)
	Callback that is called when a client is invoking a read or write service to a control block or log. More...

Enumerations
enum	AccessPolicy { ACCESS_POLICY_ALLOW , ACCESS_POLICY_DENY }
enum	IedServer_DataSetOperation {   DATASET_CREATE , DATASET_DELETE , DATASET_READ , DATASET_WRITE ,   DATASET_GET_DIRECTORY }
enum	IedServer_DirectoryCategory { DIRECTORY_CAT_LD_LIST , DIRECTORY_CAT_DATA_LIST , DIRECTORY_CAT_DATASET_LIST , DIRECTORY_CAT_LOG_LIST }
enum	IedServer_ControlBlockAccessType { IEC61850_CB_ACCESS_TYPE_READ , IEC61850_CB_ACCESS_TYPE_WRITE }

Functions
LIB61850_API void	IedServer_handleWriteAccess (IedServer self, DataAttribute *dataAttribute, WriteAccessHandler handler, void *parameter)
	Install a WriteAccessHandler for a data attribute. More...
LIB61850_API void	IedServer_handleWriteAccessForComplexAttribute (IedServer self, DataAttribute *dataAttribute, WriteAccessHandler handler, void *parameter)
	Install a WriteAccessHandler for a data attribute and for all sub data attributes. More...
LIB61850_API void	IedServer_handleWriteAccessForDataObject (IedServer self, DataObject *dataObject, FunctionalConstraint fc, WriteAccessHandler handler, void *parameter)
	Install a WriteAccessHandler for all data attributes of a data object with a specific FC. More...
LIB61850_API void	IedServer_setWriteAccessPolicy (IedServer self, FunctionalConstraint fc, AccessPolicy policy)
	Change the default write access policy for functional constraint data with a specific FC. More...
LIB61850_API void	IedServer_setReadAccessHandler (IedServer self, ReadAccessHandler handler, void *parameter)
	Install the global read access handler. More...
LIB61850_API void	IedServer_setDataSetAccessHandler (IedServer self, IedServer_DataSetAccessHandler handler, void *parameter)
	Set a handler to control access to a dataset (create, delete, read, write, list directory) More...
LIB61850_API void	IedServer_setDirectoryAccessHandler (IedServer self, IedServer_DirectoryAccessHandler handler, void *parameter)
LIB61850_API void	IedServer_setListObjectsAccessHandler (IedServer self, IedServer_ListObjectsAccessHandler handler, void *parameter)
	Set a handler to control which objects are return by the list objects services. More...
LIB61850_API void	IedServer_setControlBlockAccessHandler (IedServer self, IedServer_ControlBlockAccessHandler handler, void *parameter)
	Set a handler to control read and write access to control blocks and logs. More...
LIB61850_API void	IedServer_ignoreReadAccess (IedServer self, bool ignore)
	Temporarily ignore read requests (for testing purposes) More...

Detailed Description

Functions and callbacks to handle and restrict external access to the data model and services.

This module provides functions and callbacks to restrict external access to the data model and services of the IEC 61850 server. They can be used to implement access control mechanisms like role based access control (RBAC) and to restrict access to specific data objects and data attributes.

Typedef Documentation

IedServer_ControlBlockAccessHandler

typedef bool(* IedServer_ControlBlockAccessHandler) (void *parameter, ClientConnection connection, ACSIClass acsiClass, LogicalDevice *ld, LogicalNode *ln, const char *objectName, const char *subObjectName, IedServer_ControlBlockAccessType accessType)

Callback that is called when a client is invoking a read or write service to a control block or log.

This callback can be used to control the read and write access to control blocks and logs (SGCB, LCBs, URCBs, BRCBs, GoCBs, SVCBs, logs)

Parameters

parameter	user provided parameter
connection	client connection that is involved
acsiClass	the ACSI class of the object
ld	the logical device of the object
ln	the logical node of the object
objectName	the name of the object (e.g. data object name, data set name, log name, RCB name, ...)
subObjectName	the name of a sub element of an object or NULL
accessType	access type (read=IEC61850_CB_ACCESS_TYPE_READ or write=IEC61850_CB_ACCESS_TYPE_WRITE)

Returns

true to include the object in the service response, otherwise false

IedServer_DataSetAccessHandler

typedef bool(* IedServer_DataSetAccessHandler) (void *parameter, ClientConnection connection, IedServer_DataSetOperation operation, const char *datasetRef)

Callback that is called when the client is calling a dataset operation (create, delete, read, write, list directory)

Note

This callback is called before the IedServer_RCBEventHandler and only in case of operations (RCB_EVENT_GET_PARAMETER, RCB_EVENT_SET_PARAMETER, RCB_EVENT_ENABLE

Parameters

parameter	user provided parameter
connection	client connection that is involved
operation	one of the following operation types: DATASET_CREATE, DATASET_DELETE, DATASET_READ, DATASET_WRITE, DATASET_GET_DIRECTORY

Returns

true to allow operation, false to deny operation

IedServer_DirectoryAccessHandler

typedef bool(* IedServer_DirectoryAccessHandler) (void *parameter, ClientConnection connection, IedServer_DirectoryCategory category, LogicalDevice *logicalDevice)

IedServer_ListObjectsAccessHandler

typedef bool(* IedServer_ListObjectsAccessHandler) (void *parameter, ClientConnection connection, ACSIClass acsiClass, LogicalDevice *ld, LogicalNode *ln, const char *objectName, const char *subObjectName, FunctionalConstraint fc)

Callback that is called when a client is invoking a list objects service.

This callback can be used to control the list object access to specific objects and is called for each object that are subject to a client request.

Parameters

parameter	user provided parameter
connection	client connection that is involved
acsiClass	the ACSI class of the object
ld	the logical device of the object
ln	the logical node of the object
objectName	the name of the object (e.g. data object name, data set name, log name, RCB name, ...)
subObjectName	the name of a sub element of an object or NULL
fc	the functional constraint of the object of IEC61850_FC_NONE when the object has no FC.

Returns

true to include the object in the service response, otherwise false

ReadAccessHandler

typedef MmsDataAccessError(* ReadAccessHandler) (LogicalDevice *ld, LogicalNode *ln, DataObject *dataObject, FunctionalConstraint fc, ClientConnection connection, void *parameter)

callback handler to control client read access to data attributes

User provided callback function to control MMS client read access to IEC 61850 data objects. The application is to allow read access to data objects for specific clients only. It can be used to implement a role based access control (RBAC).

Parameters

ld	the logical device the client wants to access
ln	the logical node the client wants to access
dataObject	the data object the client wants to access
fc	the functional constraint of the access
connection	the client connection that causes the access
parameter	the user provided parameter

Returns

DATA_ACCESS_ERROR_SUCCESS if access is accepted, DATA_ACCESS_ERROR_OBJECT_ACCESS_DENIED if access is denied.

WriteAccessHandler

typedef MmsDataAccessError(* WriteAccessHandler) (DataAttribute *dataAttribute, MmsValue *value, ClientConnection connection, void *parameter)

callback handler to intercept/control client write access to data attributes

User provided callback function to intercept/control MMS client access to IEC 61850 data attributes. The application can install the same handler multiple times and distinguish data attributes by the dataAttribute parameter. This handler can be used to perform write access control do data attributes. One application can be to allow write access only from a specific client. Another application could be to check if the value is in the allowed range before the write is accepted. When the callback returns DATA_ACCESS_ERROR_SUCCESS the write access is accepted and the stack will update the value automatically. When the callback returns DATA_ACCESS_ERROR_SUCCESS_NO_UPDATE the write access is accepted but the stack will not update the value automatically.

Parameters

the	data attribute that has been written by an MMS client.
the	value the client want to write to the data attribute
connection	the connection object of the client connection that invoked the write operation
parameter	the user provided parameter

Returns

DATA_ACCESS_ERROR_SUCCESS, or DATA_ACCESS_ERROR_SUCCESS_NO_UPDATE if access is accepted, DATA_ACCESS_ERROR_OBJECT_ACCESS_DENIED if access is denied.

Enumeration Type Documentation

AccessPolicy

enum AccessPolicy

Enumerator
ACCESS_POLICY_ALLOW
ACCESS_POLICY_DENY

IedServer_ControlBlockAccessType

enum IedServer_ControlBlockAccessType

Enumerator
IEC61850_CB_ACCESS_TYPE_READ
IEC61850_CB_ACCESS_TYPE_WRITE

IedServer_DataSetOperation

enum IedServer_DataSetOperation

Enumerator
DATASET_CREATE
DATASET_DELETE
DATASET_READ
DATASET_WRITE
DATASET_GET_DIRECTORY

IedServer_DirectoryCategory

enum IedServer_DirectoryCategory

Enumerator
DIRECTORY_CAT_LD_LIST
DIRECTORY_CAT_DATA_LIST
DIRECTORY_CAT_DATASET_LIST
DIRECTORY_CAT_LOG_LIST

Function Documentation

IedServer_handleWriteAccess()

LIB61850_API void IedServer_handleWriteAccess	(	IedServer	self,
		DataAttribute *	dataAttribute,
		WriteAccessHandler	handler,
		void *	parameter
	)

Install a WriteAccessHandler for a data attribute.

This instructs the server to monitor write attempts by MMS clients to specific data attributes. If a client tries to write to the monitored data attribute the handler is invoked. The handler can decide if the write access will be allowed or denied. If a WriteAccessHandler is set for a specific data attribute - the default write access policy will not be performed for that data attribute.

Note

If the data attribute has sub data attributes, the WriteAccessHandler is not set for the sub data attributes and will not be called when the sub data attribute is written directly!

Parameters

self	the instance of IedServer to operate on.
dataAttribute	the data attribute to monitor
handler	the callback function that is invoked if a client tries to write to the monitored data attribute.
parameter	a user provided parameter that is passed to the WriteAccessHandler when called.

IedServer_handleWriteAccessForComplexAttribute()

LIB61850_API void IedServer_handleWriteAccessForComplexAttribute	(	IedServer	self,
		DataAttribute *	dataAttribute,
		WriteAccessHandler	handler,
		void *	parameter
	)

Install a WriteAccessHandler for a data attribute and for all sub data attributes.

This instructs the server to monitor write attempts by MMS clients to specific data attributes. If a client tries to write to the monitored data attribute the handler is invoked. The handler can decide if the write access will be allowed or denied. If a WriteAccessHandler is set for a specific data attribute - the default write access policy will not be performed for that data attribute.

When the data attribute is a complex attribute then the handler will also be installed for all sub data attributes. When the data attribute is a basic data attribute then this function behaves like IedServer_handleWriteAccess.

Parameters

self	the instance of IedServer to operate on.
dataAttribute	the data attribute to monitor
handler	the callback function that is invoked if a client tries to write to the monitored data attribute.
parameter	a user provided parameter that is passed to the WriteAccessHandler when called.

IedServer_handleWriteAccessForDataObject()

LIB61850_API void IedServer_handleWriteAccessForDataObject	(	IedServer	self,
		DataObject *	dataObject,
		FunctionalConstraint	fc,
		WriteAccessHandler	handler,
		void *	parameter
	)

Install a WriteAccessHandler for all data attributes of a data object with a specific FC.

Parameters

self	the instance of IedServer to operate on.
dataObject	the data object to monitor
fc	the functional constraint to monitor
handler	the callback function that is invoked if a client tries to write to the monitored data attribute.
parameter	a user provided parameter that is passed to the WriteAccessHandler when called.

IedServer_ignoreReadAccess()

LIB61850_API void IedServer_ignoreReadAccess	(	IedServer	self,
		bool	ignore
	)

Temporarily ignore read requests (for testing purposes)

Parameters

self	the instance of IedServer to operate on.
ignore	true to ignore read requests, false to handle read requests.

IedServer_setControlBlockAccessHandler()

LIB61850_API void IedServer_setControlBlockAccessHandler	(	IedServer	self,
		IedServer_ControlBlockAccessHandler	handler,
		void *	parameter
	)

Set a handler to control read and write access to control blocks and logs.

Parameters

handler	the callback handler to be used
parameter	a user provided parameter that is passed to the handler.

IedServer_setDataSetAccessHandler()

LIB61850_API void IedServer_setDataSetAccessHandler	(	IedServer	self,
		IedServer_DataSetAccessHandler	handler,
		void *	parameter
	)

Set a handler to control access to a dataset (create, delete, read, write, list directory)

Parameters

handler	the callback handler to be used
parameter	a user provided parameter that is passed to the handler.

IedServer_setDirectoryAccessHandler()

LIB61850_API void IedServer_setDirectoryAccessHandler	(	IedServer	self,
		IedServer_DirectoryAccessHandler	handler,
		void *	parameter
	)

IedServer_setListObjectsAccessHandler()

LIB61850_API void IedServer_setListObjectsAccessHandler	(	IedServer	self,
		IedServer_ListObjectsAccessHandler	handler,
		void *	parameter
	)

Set a handler to control which objects are return by the list objects services.

Parameters

handler	the callback handler to be used
parameter	a user provided parameter that is passed to the handler.

IedServer_setReadAccessHandler()

LIB61850_API void IedServer_setReadAccessHandler	(	IedServer	self,
		ReadAccessHandler	handler,
		void *	parameter
	)

Install the global read access handler.

The read access handler will be called for every read access before the server grants access to the client.

Parameters

self	the instance of IedServer to operate on.
handler	the callback function that is invoked if a client tries to read a data object.
parameter	a user provided parameter that is passed to the callback function.

IedServer_setWriteAccessPolicy()

LIB61850_API void IedServer_setWriteAccessPolicy	(	IedServer	self,
		FunctionalConstraint	fc,
		AccessPolicy	policy
	)

Change the default write access policy for functional constraint data with a specific FC.

Parameters

self	the instance of IedServer to operate on.
fc	the FC for which to change the default write access policy.
policy	the new policy to apply.