Set_Conversation_Encryption_Level - Setting the encryption level

The Set_Conversation_Encryption_Level (CMSCEL) call influences the value of the ENCRYPTION-LEVEL conversation characteristic. The encryption level is used to specify whether during a conversation user data is to be transferred in an encrypted form or not. The call overwrites the value of encryption_level, which was assigned in the Initialize_Conversation call.

The Set_Conversation_Encryption_Level call is only permitted in the “Initialize” state.

UPIC-Local on Unix, Linux and Windows systems: The data transfer is protected by the type of transfer being used. The Set_Conversation_Encryption_Level call is not supported.

This function is one of the additional functions of the UPIC carrier system; it is not a component of the CPI-C interface.

Syntax

CMSCEL (conversation_ID, encryption_level, return_code)

Parameters

--> conversation_ID	Conversation identifier
--> encryption_level	Specifies whether the conversation user data is to be transferred in an encrypted or unencrypted form. The following values can be used: CM_ENC_LEVEL_NONE The conversation user data is to be transferred in an unencrypted form. CM_ENC_LEVEL_3 The user data is to be transferred in an encrypted form using the AES algorithm. An RSA key with a key length of 1024 bits is used for exchange of the AES key. CM_ENC_LEVEL_4 The user data is to be transferred in an encrypted form using the AES algorithm. An RSA key with a key length of 2048 bits is used for exchange of the AES key. CM_ENC_LEVEL_5 User data are encrypted and authenticated, using the AES/GCM algorithm. The Diffie-Hellman algorithm is used to exchange the AES key with a length of 2048 bits.
<-- return_code	Result of the function call.

Result ( return_code )

CM_OK

The call is OK.

CM_CALL_NOT_SUPPORTED

This return code only applies to Unix, Linux and Windows systems.
The function is not supported. This return code only occurs for UPIC-L. It indicates to the program that encryption is not necessary.

CM_PROGRAM_STATE_CHECK

The conversation is not in the “Initialize” state.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID is invalid, or the value of encryption_level is undefined.

CM_PRODUCT_SPECIFIC_ERROR

The UPIC instance could not be found.

CM_ENCRYPTION_NOT_SUPPORTED

Encryption is not available for this conversation for one of the following reasons:

• the software requirements are not met.

• the UTM partner application does not want to implement encryption because the UPIC-L client is trusted.

CM_ENCRYPTION_LEVEL_NOT_SUPPORTED

Encryption with the specified encryption level (encryption_level) is not supported by UPIC.

State change

If there are no errors the function returns CM_OK. The call does not change the state of the conversation.

Notes

• If the return code is not CM_OK, the ENCRYPTION_LEVEL characteristic remains unchanged.

• If the encryption level requested by the UTM application is higher than the one on the UPIC client side, the higher encryption level is implemented. Or in other words, if the UTM application requests a certain level of encryption, the UPIC client encrypts the data on this level regardless of the level of encryption set by the UPIC application.

• If there is no communication connection set up to the UTM partner application at the time when the call is made, the function terminates with the CM_OK return code The system decides when the subsequent Allocate call is made whether the requested encryption level is to be implemented.

Behavior in the event of errors

CM_CALL_NOT_SUPPORTED

This return code only applies to Unix, Linux and Windows systems.
Is not necessarily an error: If an application is intended for both UPIC-L and for UPIC-R, this return code just means that the application is linked to a UPIC-L library. In this case encryption is not necessary. The program can take note of this return code and avoid making further calls requesting encryption.

CM_PROGRAM_STATE_CHECK

Modify program.

CM_PROGRAM_PARAMETER_CHECK

Modify program.

CM_PRODUCT_SPECIFIC_ERROR

The operating system cannot provide sufficient memory for the internal buffers. Check whether the memory requirements of your program are too high and if necessary reboot your system.

CM_ENCRYPTION_NOT_SUPPORTED

Is not necessarily an error: If a UPIC-R application is communicating with several UTM partners some of which implement encryption and some of which do not, then this return code just means that it is communicating with an application which either cannot or doesn’t want to implement encryption. In this case encryption is not possible. The program can take note of this return code and avoid making further calls requesting encryption.

CM_ENCRYPTION_LEVEL_NOT_SUPPORTED

The UPIC library has possibly loaded an old encryption library. Make sure that the encryption library of the latest openUTM client version is installed and is also loaded. Note the search sequence for libraries in the different operating systems.

Function declaration: Set_Conversation_Encryption_Level

CM_ENTRY Set_Conversation_Encryption_Level 
                      unsigned char       CM_PTR conversation_ID,
                      CM_ENCRYPTION_LEVEL CM_PTR encryption_level,
                      CM_RETURN_CODE      CM_PTR return_code )