libs2opc_client_config_custom.h File Reference

Additional client configuration facilities for non-XML configuration of the client or non-essential advanced configuration. More...

#include <stdbool.h>
#include "libs2opc_client_config.h"
#include "libs2opc_common_config.h"

Go to the source code of this file.

Functions
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetPreferredLocaleIds (size_t nbLocales, const char **localeIds)
	Client configuration without XML. More...
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetApplicationDescription (const char *applicationUri, const char *productUri, const char *defaultAppName, const char *defaultAppNameLocale, OpcUa_ApplicationType applicationType)
	Defines client application description. More...
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetPKIprovider (SOPC_PKIProvider *pki)
	Defines the PKI provider that will be in charge of validating certificates received by client. More...
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetKeyCertPairFromPath (const char *clientCertPath, const char *clientKeyPath, bool encrypted)
	Sets asymmetrical certificate and key of client from file paths. Certificate files shall use DER format, key file shall use DER or PEM format. More...
SOPC_ReturnStatus	SOPC_ClientConfigHelper_SetKeyCertPairFromBytes (size_t certificateNbBytes, const unsigned char *clientCertificate, size_t keyNbBytes, const unsigned char *clientPrivateKey)
	Sets asymmetrical certificate and key of client from byte arrays. Certificate shall be in DER format, key file shall be in DER or PEM format. More...
SOPC_SecureConnection_Config *	SOPC_ClientConfigHelper_CreateSecureConnection (const char *userDefinedId, const char *endpointUrl, OpcUa_MessageSecurityMode secuMode, SOPC_SecurityPolicy_URI secuPolicy)
	Creates a new secure channel configuration in client that shall be completed by using the functions below (SOPC_SecureConnectionConfig_SetServerCertificateFromPath or SOPC_SecureConnectionConfig_SetServerCertificateFromBytes, etc.) More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetExpectedEndpointsDescription (SOPC_SecureConnection_Config *secConnConfig, const OpcUa_GetEndpointsResponse *getEndpointsResponse)
	Defines the Secure Connection expected EndpointsDescription from given GetEndpointsResponse. If defined, it is used for verification of coherence during the session activation. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetReverseConnection (SOPC_SecureConnection_Config *secConnConfig, const char *clientReverseEndpointUri)
	Sets the Secure Connection in reverse connection mode. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetReqLifetime (SOPC_SecureConnection_Config *secConnConfig, uint32_t reqLifetime)
	Defines the lifetime requested to the server for this secure connection (symmetric keys renewal) A default value is used if not set. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetServerCertificateFromPath (SOPC_SecureConnection_Config *secConnConfig, const char *serverCertPath)
	Defines the server certificate DER file path to be used to establish the secure connection. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetServerCertificateFromBytes (SOPC_SecureConnection_Config *secConnConfig, size_t certificateNbBytes, const unsigned char *serverCertificate)
	Defines the server certificate DER encoded bytes to be used to establish the secure connection. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetAnonymous (SOPC_SecureConnection_Config *secConnConfig, const char *userPolicyId)
	Defines the user authentication mode as anonymous for the secure connection and set the associated user policy Id to be used in server. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetUserName (SOPC_SecureConnection_Config *secConnConfig, const char *userPolicyId, const char *userName, const char *password)
	Defines the user authentication mode as username/password for the secure connection, sets the associated user policy Id to be used in server and sets the username/password to be used for authentication. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetUserX509FromPaths (SOPC_SecureConnection_Config *secConnConfig, const char *userPolicyId, const char *userCertPath, const char *userKeyPath, bool encrypted)
	Defines the user authentication mode as X509 certificate for the secure connection, sets the associated user policy Id to be used in server and sets the certificate/key paths to be used for authentication. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetUserX509FromBytes (SOPC_SecureConnection_Config *secConnConfig, const char *userPolicyId, size_t certificateNbBytes, const unsigned char *userCertificate, size_t keyNbBytes, const unsigned char *userPrivateKey)
	Sets asymmetrical certificate and key of user from byte arrays. Certificate shall be in DER format, key file shall be in DER or PEM format. More...
SOPC_ReturnStatus	SOPC_SecureConnectionConfig_SetServerCertUpdateCb (SOPC_SecureConnection_Config *secConnConfig, SOPC_KeyCertPairUpdateCb *serverCertUpdateCb, uintptr_t updateParam)
	Sets the callback to be called if the server certificate held by SOPC_CertHolder is updated at runtime using SOPC_KeyCertPair_UpdateFromBytes (manually called by application code). The callback content shall implement the consequence of an update on the secure connection at runtime. More...
SOPC_ReturnStatus	SOPC_ClientConfigHelper_GetSecureConnectionConfigs (size_t *nbScConfigs, SOPC_SecureConnection_Config ***scConfigArray)
	Gets the configured secure connections array. More...

Detailed Description

Additional client configuration facilities for non-XML configuration of the client or non-essential advanced configuration.

Note

TLDR: if client configuration is done through XML configuration files, you might ignore this header.

Function Documentation

SOPC_ClientConfigHelper_SetPreferredLocaleIds()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetPreferredLocaleIds	(	size_t	nbLocales,
		const char **	localeIds
	)

Client configuration without XML.

Defines client preferred locales ids sorted by preference from an array of locale strings.

Parameters

nbLocales	The number of locales defined in the array. It might be 0 if no locale defined (only default exist).
localeIds	The array of locales sorted by preference order. Array and its content is copied by function.

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if localeIds is invalid when nbLocales > 0 or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, preferred localesIds already defined, client connection initiated).

SOPC_ClientConfigHelper_SetApplicationDescription()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetApplicationDescription	(	const char *	applicationUri,
		const char *	productUri,
		const char *	defaultAppName,
		const char *	defaultAppNameLocale,
		OpcUa_ApplicationType	applicationType
	)

Defines client application description.

Parameters

applicationUri	The globally unique identifier for the application instance. This URI is used as ServerUri in Services if the application is a Server.
productUri	The globally unique identifier for the product.
defaultAppName	The name of the application using the default locale language.
defaultAppNameLocale	The default locale if any. If defined it shall exists in supported locales.
applicationType	The type of application, it shall be one of the OpcUa_ApplicationType_Client* types

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if applicationUri, productUri or defaultAppName are invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, application description already set, client connection initiated).

SOPC_ClientConfigHelper_SetPKIprovider()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetPKIprovider

(

SOPC_PKIProvider *

pki

)

Defines the PKI provider that will be in charge of validating certificates received by client.

Parameters

pki	The PKI provider to be used. It will be automatically deallocated using SOPC_PKIProvider_Free on call to SOPC_ClientConfigHelper_Clear.

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if pki is invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, PKI already defined, server already started).

Note

A default PKI provider compliant with OPC UA standard is provided in sopc_pki_stack.h

SOPC_ClientConfigHelper_SetKeyCertPairFromPath()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetKeyCertPairFromPath	(	const char *	clientCertPath,
		const char *	clientKeyPath,
		bool	encrypted
	)

Sets asymmetrical certificate and key of client from file paths. Certificate files shall use DER format, key file shall use DER or PEM format.

Parameters

clientCertPath	Path to client certificate file at DER format (copied by function)
clientKeyPath	Path to client key file at DER or PEM format (copied by function)
encrypted	Whether if the key is encrypted or not

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if clientCertPath or clientKeyPath are invalid or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, key/cert pair already set, connection initiated).

SOPC_ClientConfigHelper_SetKeyCertPairFromBytes()

SOPC_ReturnStatus SOPC_ClientConfigHelper_SetKeyCertPairFromBytes	(	size_t	certificateNbBytes,
		const unsigned char *	clientCertificate,
		size_t	keyNbBytes,
		const unsigned char *	clientPrivateKey
	)

Sets asymmetrical certificate and key of client from byte arrays. Certificate shall be in DER format, key file shall be in DER or PEM format.

Parameters

certificateNbBytes	Number of bytes in clientCertificate array
clientCertificate	Array of bytes containing client certificate at DER format (copied by function)
keyNbBytes	Number of bytes in clientPrivateKey array
clientPrivateKey	Array of bytes containing client key file at DER or PEM format (copied by function)

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if certificateNbBytes, clientCertificate, keyNbBytes or clientPrivateKey are invalid (0 or NULL) or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, key/cert pair already set).

SOPC_ClientConfigHelper_CreateSecureConnection()

SOPC_SecureConnection_Config* SOPC_ClientConfigHelper_CreateSecureConnection	(	const char *	userDefinedId,
		const char *	endpointUrl,
		OpcUa_MessageSecurityMode	secuMode,
		SOPC_SecurityPolicy_URI	secuPolicy
	)

Creates a new secure channel configuration in client that shall be completed by using the functions below (SOPC_SecureConnectionConfig_SetServerCertificateFromPath or SOPC_SecureConnectionConfig_SetServerCertificateFromBytes, etc.)

Parameters

userDefinedId	A user defined identifier to retrieve the secure connection configuration using SOPC_ClientConfigHelper_GetConfigFromId.
endpointUrl	URL of the endpoint: opc.tcp://<host>:<port>[/<name>]
secuMode	Security mode required for this SecureConnection: None, Sign or SignAndEncrypt. If value different from None, SOPC_SecureConnectionConfig_SetServerCertificate* shall be called.
secuPolicy	Security policy URI required for this SecureConnection. If value different from None, SOPC_SecureConnectionConfig_SetServerCertificate* shall be called.

Note

Returned SOPC_SecureConnection_Config is owned by library and shall not be freed.

Returns

SOPC_SecureConnectionConfig pointer to configuration structure to be filled with SOPC_SecureConnectionConfig_Set* functions (SOPC_SecureConnectionConfig_SetServerCertificateFromPath, etc.). Otherwise Returns NULL if no more configuration slots are available (see SOPC_MAX_CLIENT_SECURE_CONNECTIONS_CONFIG).

SOPC_SecureConnectionConfig_SetExpectedEndpointsDescription()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetExpectedEndpointsDescription	(	SOPC_SecureConnection_Config *	secConnConfig,
		const OpcUa_GetEndpointsResponse *	getEndpointsResponse
	)

Defines the Secure Connection expected EndpointsDescription from given GetEndpointsResponse. If defined, it is used for verification of coherence during the session activation.

Parameters

secConnConfig	The secure connection configuration to modify
getEndpointsResponse	The client expected endpoint description to be returned by the server during connection. Connection will be aborted otherwise. The response will be copied and might be deallocated after call.

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (already used for a connection or expected endpoint already set), SOPC_STATUS_OUT_OF_MEMORY if OOM raised.

SOPC_SecureConnectionConfig_SetReverseConnection()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetReverseConnection	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	clientReverseEndpointUri
	)

Sets the Secure Connection in reverse connection mode.

Parameters

secConnConfig	The secure connection configuration to set
clientReverseEndpointUri	The client reverse endpoint URI to be used to listen for reverse connection from the server

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (already used for a connection or reverse endpoint already set), SOPC_STATUS_OUT_OF_MEMORY if OOM raised.

SOPC_SecureConnectionConfig_SetReqLifetime()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetReqLifetime	(	SOPC_SecureConnection_Config *	secConnConfig,
		uint32_t	reqLifetime
	)

Defines the lifetime requested to the server for this secure connection (symmetric keys renewal) A default value is used if not set.

Parameters

secConnConfig	The secure connection configuration to set
reqLifetime	Requested lifetime in millisecond for the secure channel between 2 renewal.

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (already used for a connection or reverse endpoint already set).

SOPC_SecureConnectionConfig_SetServerCertificateFromPath()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetServerCertificateFromPath	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	serverCertPath
	)

Defines the server certificate DER file path to be used to establish the secure connection.

Parameters

secConnConfig	The secure connection configuration to set
serverCertPath	The server certificate DER file path

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (already used for a connection or reverse endpoint already set), SOPC_STATUS_OUT_OF_MEMORY if OOM raised.

SOPC_SecureConnectionConfig_SetServerCertificateFromBytes()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetServerCertificateFromBytes	(	SOPC_SecureConnection_Config *	secConnConfig,
		size_t	certificateNbBytes,
		const unsigned char *	serverCertificate
	)

Defines the server certificate DER encoded bytes to be used to establish the secure connection.

Parameters

secConnConfig	The secure connection configuration to set
certificateNbBytes	The server certificate DER encoded bytes size
serverCertificate	The server certificate DER encoded bytes

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (already used for a connection or reverse endpoint already set), SOPC_STATUS_OUT_OF_MEMORY if OOM raised.

SOPC_SecureConnectionConfig_SetAnonymous()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetAnonymous	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	userPolicyId
	)

Defines the user authentication mode as anonymous for the secure connection and set the associated user policy Id to be used in server.

Note

By default, the user authentication mode is anonymous and user policy Id is ""

Parameters

secConnConfig	The secure connection configuration to set
userPolicyId	The user policy Id to be used in server for anonymous (might not be verified by server for anonymous)

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (user authentication mode already set).

SOPC_SecureConnectionConfig_SetUserName()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetUserName	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	userPolicyId,
		const char *	userName,
		const char *	password
	)

Defines the user authentication mode as username/password for the secure connection, sets the associated user policy Id to be used in server and sets the username/password to be used for authentication.

Parameters

secConnConfig	The secure connection configuration to set
userPolicyId	The user policy Id to be used in server for username/password
userName	The username to be used for authentication or NULL to be retrieved from the callback defined with SOPC_ClientConfigHelper_SetUserNamePasswordCallback.
password	The password to be used for authentication or NULL to be retrieved from the callback defined with SOPC_ClientConfigHelper_SetUserNamePasswordCallback. Note: the password should not be hardcoded string in the code.

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (user authentication mode already set).

SOPC_SecureConnectionConfig_SetUserX509FromPaths()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetUserX509FromPaths	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	userPolicyId,
		const char *	userCertPath,
		const char *	userKeyPath,
		bool	encrypted
	)

Defines the user authentication mode as X509 certificate for the secure connection, sets the associated user policy Id to be used in server and sets the certificate/key paths to be used for authentication.

Parameters

secConnConfig	The secure connection configuration to set
userPolicyId	The user policy Id to be used in server for X509 certificate
userCertPath	The path to the user certificate file at DER format (copied by function)
userKeyPath	The path to the user key file at DER or PEM format (copied by function)
encrypted	Whether if the key is encrypted or not

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized) or connection config cannot be modified (user authentication mode already set).

SOPC_SecureConnectionConfig_SetUserX509FromBytes()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetUserX509FromBytes	(	SOPC_SecureConnection_Config *	secConnConfig,
		const char *	userPolicyId,
		size_t	certificateNbBytes,
		const unsigned char *	userCertificate,
		size_t	keyNbBytes,
		const unsigned char *	userPrivateKey
	)

Sets asymmetrical certificate and key of user from byte arrays. Certificate shall be in DER format, key file shall be in DER or PEM format.

Parameters

secConnConfig	The secure connection configuration to set
userPolicyId	The user policy Id to be used in server for X509 certificate
certificateNbBytes	Number of bytes in clientCertificate array
userCertificate	Array of bytes containing user certificate at DER format (copied by function)
keyNbBytes	Number of bytes in clientPrivateKey array
userPrivateKey	Array of bytes containing user key file at DER or PEM format (copied by function)

Returns

SOPC_STATUS_OK in case of success, otherwise SOPC_STATUS_INVALID_PARAMETERS if certificateNbBytes, userCertificate, keyNbBytes or userPrivateKey are invalid (0 or NULL) or SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, key/cert pair already set).

SOPC_SecureConnectionConfig_SetServerCertUpdateCb()

SOPC_ReturnStatus SOPC_SecureConnectionConfig_SetServerCertUpdateCb	(	SOPC_SecureConnection_Config *	secConnConfig,
		SOPC_KeyCertPairUpdateCb *	serverCertUpdateCb,
		uintptr_t	updateParam
	)

Sets the callback to be called if the server certificate held by SOPC_CertHolder is updated at runtime using SOPC_KeyCertPair_UpdateFromBytes (manually called by application code). The callback content shall implement the consequence of an update on the secure connection at runtime.

Warning

It is mandatory to set this callback to allow possible call to the certificate update function SOPC_KeyCertPair_UpdateFromBytes.

Parameters

secConnConfig	The secure connection configuration to set
serverCertUpdateCb	The callback to be called in case of update of server certificate configuration at runtime
updateParam	The parameter to be passed to the callback containing the necessary context

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized, callback already set, connection already finalized).

SOPC_ClientConfigHelper_GetSecureConnectionConfigs()

SOPC_ReturnStatus SOPC_ClientConfigHelper_GetSecureConnectionConfigs	(	size_t *	nbScConfigs,
		SOPC_SecureConnection_Config ***	scConfigArray
	)

Gets the configured secure connections array.

Parameters

[out]	nbScConfigs	The number of secure connection configurations
[out]	scConfigArray	The array of secure connection configuration pointers

Returns

SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameters, SOPC_STATUS_INVALID_STATE if the configuration is not possible (wrapper not initialized)