Extract_Conversation_Encryption_Level - Querying encryption level

A program uses the Extract_Conversation_Encryption_Level (CMECEL) call to extract the encryption levels which have been set up. The Extract_Conversation_Encryption_Level call is permitted in the following states: “Initialize”, “Send” and “Receive”.

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

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

Syntax

CMECEL (conversation_ID, encryption_level, return_code)

Parameters

--> conversation_ID	Conversation identifier
<-- encryption_level	the status_received variable can have one of the following values: CM_ENC_LEVEL_NONE The user data of the conversation is transferred in unencrypted form. CM_ENC_LEVEL_3 The user data is encrypted before transfer 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 encrypted before transfer 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 The user data is encrypted before transfer using the AES algorithm. For the exchange of the AES key, an ECDH algorithm with a key length of 2048 bits is used.
<-- return_code	Result of the function call.

Result (return_code)

CM_OK

The call is OK.

CM_CALL_NOT_SUPPORTED

only for UPIC local on Unix, Linux and Windows systems

The function is not supported. This return code indicates to the program that encryption is not necessary.

CM_PROGRAM_STATE_CHECK

The conversation is in either the “Start” or the “Reset” state.

CM_PROGRAM_PARAMETER_CHECK

The value of conversation_ID is invalid.

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 UTM partner application does not want encryption because the UPIC client is trusted.

• the UPIC client cannot implement encryption because the encryption functionality is not available.

State change

The call does not alter the state of the conversation.

Notes

• CMECEL can only ever supply the current value of the encryption level. The encryption level can always be modified using a subsequent CPI-C call.

• If several conversations are established with the same partner application (or in other words, the communication connection is not set up and cleared down every time), the result of CMECEL will be CMINIT CM_OK after the first call, but after all subsequent CMINIT calls it will be CM_ENCRYPTION_NOT_SUPPORTED. The UPIC library only establishes the connection to the partner application after the first CMALLOC call and thus specifies the encryption option.

Behavior in event of errors

CM_CALL_NOT_SUPPORTED

This return code only applies to Unix, Linux and Windows systems.
This is not necessarily an error: If the application is intended for both UPIC-L and UPIC-R this return code just means that the application is linked to a UPIC-L library. If this is the 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 requirement of your program is too high and if necessary reboot your system.

CM_ENCRYPTION_NOT_SUPPORTED

The encryption requirements are not met.

This is not necessarily an error: If a UPIC-R application is communicating with several UTM partners some of which implement data encryption and some of which do not, then this return code just means that the UTM application the current application is communicating with either cannot or does not wish 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.

Function declaration: Extract_Conversation_Encryption_Level

Extract_Conversation_Encryption_Level (unsigned char CM_PTR conversation_ID,
                                 CM_ENCRYPTION_LEVEL CM_PTR encryption_level,
                                 CM_RETURN_CODE      CM_PTR return_code )