CmpTls Implementation Library Documentation ¶ Company System Title CmpTls Implementation Version 3.5.17.0 Categories System|SysLibs Author CODESYS Development GmbH Placeholder CmpTls Implementation Description 1 ¶ This library provies access to the TLS Implementaiton of the runtime system. The CmpTlsCreateContext and CmpTlsCreateContext2 functions are used to setup a TLS specific object which may be used in other libraries such as SysSocket2. The ohter functions provied access to an TLS implementation on static buffers. This can be used to implement the TLS protocol on some third party protocol. The classical implementation with sockets is provied within the SysSocket2 library. Contents: ¶ CmpTlsAccept (Function) CmpTlsBufferDataReceived (Function) CmpTlsBufferDataSent (Function) CmpTlsBufferDataToSendAvailable (Function) CmpTlsBufferOpen (Function) CmpTlsClose (Function) CmpTlsConnect (Function) CmpTlsCreateContext (Function) CmpTlsCreateContext2 (Function) CmpTlsFreeContext (Function) CmpTlsRead (Function) CmpTlsShutdown (Function) CmpTlsWrite (Function) Indices and tables ¶ 1 Based on CmpTls Implementation.library, last modified 20.04.2021, 15:57:07. LibDoc 4.4.0.0-b.27 The content file CmpTls Implementation.clean.json was generated with CODESYS V3.5 SP16 Patch 3 on 20.04.2021, 15:57:07.

CmpTlsBufferDataReceived (FUN) ¶ FUNCTION CmpTlsBufferDataReceived : RTS_IEC_RESULT This function is used to indicate that the Rx buffer contains new TLS data. Call this function is new data have arrived. All data of the buffer has to be consumed by the TLS implementation before overwritting the existing data and calling this funciton. Call TlsRead until the corresponding error code is returned. If not all data is consumed the TLS stream will be broken and the data can’t be decrypted anymore. The Rx buffer will not be changed. InOut: Scope Name Type Comment Return CmpTlsBufferDataReceived RTS_IEC_RESULT Input hTlsConn RTS_IEC_HANDLE Handle to the TLS connection. Must have been created with CmpTlsBufferOpen

CmpTlsAccept (FUN) ¶ FUNCTION CmpTlsAccept : RTS_IEC_RESULT Starts handshaking on the server side. The client has to initiate the handshaking. This is the first function call on the serverside after establishing the unterlaying connection. Data has to be received first. This function will is likley to read and write data. InOut: Scope Name Type Comment Return CmpTlsAccept RTS_IEC_RESULT Result of this operation. May be one of these values: ERR_OK: No error. Everything worked as expected. ERR_NOTINITIALIZED: The TLS component was not initialized proberly. ERR_TLS_CONNECTION_CLOSED: The TLS connection is closed. Use TlsShutdown to shutdown locally. ERR_TLS_WANT_READ: The operation needs TO read data FROM the IO system. There is no data available. ERR_TLS_WANT_WRITE: The operation needs to write data to the IO system. This is not possible. ERR_TLS_RETRY_OPERATION: Something went wrong. Try the same function call again ERR_TLS_IO_SYSTEM: An error in the unterlaying IO system. ERR_TLS_INTERNAL: An internal Error of the TLS Component ERR_FAILED: Unknown error. Input hTlsConn RTS_IEC_HANDLE Handle of the TLS connection, created with one of the TLSxxxOpen functions

CmpTlsBufferDataSent (FUN) ¶ FUNCTION CmpTlsBufferDataSent : RTS_IEC_RESULT This function is used to indicate that the data written by the TLS implementation has been sent to the peer. If this function is called the TLS implementation will start writing it’s output at the beginning of the Tx buffer again. Call this function if the data of the Tx buffer has been sent. The length parameter of the Tx buffer will be set to 0. InOut: Scope Name Type Comment Return CmpTlsBufferDataSent RTS_IEC_RESULT Input hTlsConn RTS_IEC_HANDLE Handle to the TLS connection. Must have been created with CmpTlsBufferOpen

CmpTlsBufferDataToSendAvailable (FUN) ¶ FUNCTION CmpTlsBufferDataToSendAvailable : BOOL This function is called to determine if the tx buffer contains data which should be sent to the peer. InOut: Scope Name Type Comment Return CmpTlsBufferDataToSendAvailable BOOL Input hTlsConn RTS_IEC_HANDLE Handle to the TLS connection. Must have been created with CmpTlsBufferOpen

CmpTlsBufferOpen (FUN) ¶ FUNCTION CmpTlsBufferOpen : RTS_IEC_HANDLE Create a TLS connection around any existing transport media. There are two buffers needed: a send and a receive buffer. Put the data received from the peer to the Rx buffer. The data written by the TLS implementation will be put to the Tx buffer. This buffer has to be sent to the peer after calling the connect, accept or write functions. Maybe after calling the read function the buffer has to be sent too. This depends on internal TLS protocol stuff (change of session keys etc) which may occur at any time. This will be indicated throuth the corresponding returned flag. The TLS connection will be established explicit by calling TSLConnect, or on the server side by calling the Accept function. If the handshaking hasn’t finished the read and write functions will internally finish the handshaking until the connection is established. The implementation will start writing at the beginning at each call. If the function indicated that the the data must be sent the next call will overwrite the data in the Tx buffer. So the caller must handle the data before calling the next TLS function. The buffers given here contain raw TLS protocol data. This data has to be transferred to the peer using a reliable way. The packages have to arrive completely and in the right order. Otherwise TLS won’t work. To read or to write the corresponding plaintext data use the TlsRead and TlsWrite functions. Handling is done as follows: Received data: The bytestrings pointer will point to the beginning of the data. The bytestrings max length will hold the buffers size The bytestrings length will hold the current available amount of data. The function ResetRx will not change any of the byte string. Only the internal read position will be set to the beginning of the buffer Transmit data: The bytestrings pointer will point to the of the empty writing buffer. The bytestrings max length will hold the buffer size The bytestrings length will contain the amount of data written by the TLS implementation. The function ResetTx will reset the internal write position. The length of the bytestring will be set to 0. InOut: Scope Name Type Comment Return CmpTlsBufferOpen RTS_IEC_HANDLE The handle to the created TLS connection, or RTS_INVALID_HANDLE, if operation failed. Input hTlsContext RTS_IEC_HANDLE Handle to the TLS configuration context. Create by CmpTlsCreateContext pRxBuffer POINTER TO RtsByteString Pointer to the buffer containing the data received from the peer. pTxBuffer POINTER TO RtsByteString Pointer to the buffer containing the data to be sent to the peer. pResult POINTER TO RTS_IEC_RESULT Result of this operation. Possible values: ERR_OK: The TLS connection was created successful. ERR_NOMEMORY: The TLS connection could not be created. No memory available ERR_INVALID_HANDLE: The TLS connection could not be created. The given context handle is invalid. ERR_PARAMETER: Some parameters where inconsistent or wrong.

CmpTlsClose (FUN) ¶ FUNCTION CmpTlsClose : RTS_IEC_RESULT lose the TLS connection. All data will be cleand up. The handle used for creating the connection will be closed too. No shutdown is done here. This is allowed by the TLS protocol. InOut: Scope Name Type Comment Return CmpTlsClose RTS_IEC_RESULT Result of this operation. May be one of these values: ERR_OK: No error. Everything worked as expected. ERR_FAILED: Unknown error. Input hTlsConn RTS_IEC_HANDLE Handle of the TLS connection, created with one of the TLSxxxOpen functions

CmpTlsConnect (FUN) ¶ FUNCTION CmpTlsConnect : RTS_IEC_RESULT Starts handshaking on the client side. This data is likley to read and write data. InOut: Scope Name Type Comment Return CmpTlsConnect RTS_IEC_RESULT Result of this operation. May be one of these values: ERR_OK: No error. Everything worked as expected. ERR_NOTINITIALIZED: The TLS component was not initialized proberly. ERR_TLS_CONNECTION_CLOSED: The TLS connection is closed. Use TlsShutdown to shutdown locally. ERR_TLS_WANT_READ: The operation needs TO read data FROM the IO system. There is no data available. ERR_TLS_WANT_WRITE: The operation needs to write data to the IO system. This is not possible. ERR_TLS_RETRY_OPERATION: Something went wrong. Try the same function call again ERR_TLS_IO_SYSTEM: An error in the unterlaying IO system. ERR_TLS_INTERNAL: An internal Error of the TLS Component ERR_FAILED: Unknown error. Input hTlsConn RTS_IEC_HANDLE Handle of the TLS connection, created with one of the TLSNewConn functions

CmpUserMgr ¶ Functions Authentication UserMgrChangeMyPassword (Function) UserMgrGetSessionUser (Function) UserMgrIsActive (Function) UserMgrLogin (Function) UserMgrLogout (Function) UserMgrRelogin (Function) Authorization UserMgrGetUserAccessRights (Function) UserMgrHasUserAccessRights (Function) Grouphandling UserMgrGroupAdd (Function) UserMgrGroupAddUser (Function) UserMgrGroupGetFirst (Function) UserMgrGroupGetFirstUser (Function) UserMgrGroupGetHandle (Function) UserMgrGroupGetName (Function) UserMgrGroupGetNext (Function) UserMgrGroupGetNextUser (Function) UserMgrGroupRemove (Function) UserMgrGroupRemoveUser (Function) Objecthandling UserMgrObjectAdd (Function) UserMgrObjectAddGroup (Function) UserMgrObjectClearRights (Function) UserMgrObjectGetFirstChild (Function) UserMgrObjectGetFirstGroup (Function) UserMgrObjectGetGroupRights (Function) UserMgrObjectGetHandle (Function) UserMgrObjectGetName (Function) UserMgrObjectGetNextChild (Function) UserMgrObjectGetNextGroup (Function) UserMgrObjectRemove (Function) UserMgrObjectRemoveGroup (Function) UserMgrObjectSetGroupDeniedRights (Function) UserMgrObjectSetGroupRights (Function) UserMgrObjectSetUsedRights (Function) Userhandling UserMgrUserAdd (Function) UserMgrUserAddInfoToUser (Function) UserMgrUserGetFirst (Function) UserMgrUserGetInfoOfUser (Function) UserMgrUserGetName (Function) UserMgrUserGetNext (Function) UserMgrUserGetProperty (Function) UserMgrUserRemove (Function) UserMgrUserRemoveInfoFromAllUsers (Function) UserMgrUserRemoveInfoFromUser (Function) UserMgrUserSetCredentials (Function) UserMgrUserSetProperty (Function)

Functions ¶ Authentication UserMgrChangeMyPassword (Function) UserMgrGetSessionUser (Function) UserMgrIsActive (Function) UserMgrLogin (Function) UserMgrLogout (Function) UserMgrRelogin (Function) Authorization UserMgrGetUserAccessRights (Function) UserMgrHasUserAccessRights (Function) Grouphandling UserMgrGroupAdd (Function) UserMgrGroupAddUser (Function) UserMgrGroupGetFirst (Function) UserMgrGroupGetFirstUser (Function) UserMgrGroupGetHandle (Function) UserMgrGroupGetName (Function) UserMgrGroupGetNext (Function) UserMgrGroupGetNextUser (Function) UserMgrGroupRemove (Function) UserMgrGroupRemoveUser (Function) Objecthandling UserMgrObjectAdd (Function) UserMgrObjectAddGroup (Function) UserMgrObjectClearRights (Function) UserMgrObjectGetFirstChild (Function) UserMgrObjectGetFirstGroup (Function) UserMgrObjectGetGroupRights (Function) UserMgrObjectGetHandle (Function) UserMgrObjectGetName (Function) UserMgrObjectGetNextChild (Function) UserMgrObjectGetNextGroup (Function) UserMgrObjectRemove (Function) UserMgrObjectRemoveGroup (Function) UserMgrObjectSetGroupDeniedRights (Function) UserMgrObjectSetGroupRights (Function) UserMgrObjectSetUsedRights (Function) Userhandling UserMgrUserAdd (Function) UserMgrUserAddInfoToUser (Function) UserMgrUserGetFirst (Function) UserMgrUserGetInfoOfUser (Function) UserMgrUserGetName (Function) UserMgrUserGetNext (Function) UserMgrUserGetProperty (Function) UserMgrUserRemove (Function) UserMgrUserRemoveInfoFromAllUsers (Function) UserMgrUserRemoveInfoFromUser (Function) UserMgrUserSetCredentials (Function) UserMgrUserSetProperty (Function)