KC_ENCRYPT - Create, delete, read RSA key pairs

With KC_ENCRYPT, you can create a new application’s RSA key pair, replace an application’s RSA key pair by a new pair, delete an RSA key pair or read the public key of an RSA key pair.

UTM applications on BS2000 systems also support encryption for connections with some terminal emulations. However, these connections do not use the openUTM RSA key pair. Instead, a key pair generated by VTSU-B is employed. Consequently, changing the RSA key pair of openUTM has no effect whatsoever on encryption using VTSU-B.

Prerequisites

You can only use this function, if the encryption functions are available for the application.

Encryption methods

openUTM offers encryption functions for passwords and user data (messages), in order to improve the security for connections between openUTM server applications and UPIC clients.

You will find further information on encryption in the openUTM manuals “Concepts and Functions” and “Generating Applications”.

Functional scope of KC_ENCRYPT

An RSA key pair that is valid for a specific encryption level is used for all client connections that use this encryption level. For reasons of security, you should therefore replace the RSA key pairs of your UTM application by new key pairs at regular intervals. With Encryption Level 5, the server's RSA key is only used to sign the server's Diffie-Hellman public key so that the client can uniquely assign this key to the server. This procedure, longer use of the RSA key is less critical.
For connections with Encryption Level 5, RSA keys with 2048 bits are also used, which corresponds to RSA keys of Encryption Level 4.

For this purpose, KC_ENCRYPT offers the following functions:

• Create a new RSA key pair

  KC_ENCRYPT with subopcode1=KC_CREATE_KEY makes UTM generate a new RSA key pair. However, UTM does not use this new key pair for encryption, before you activate it by dispatching a further KC_ENCRYPT call (with subopcode1=KC_ACTIVATE_KEY).

  You cannot create a new key pair unless the key pair last created with the same encryption level has already been activated with subopcode1=KC_ACTIVATE_KEY or has been deleted with subopcode1=KC_DELETE_KEY, i.e. there must be no not yet activated key pair of the same encryption level for the application.

• Delete a key pair

  You use KC_ENCRYPT with subopcode1=KC_DELETE_KEY to delete a key pair that has not yet been activated. You use KC_ENCRYPT with subopcode1 = KC_DELETE_ACTIVE_KEY to delete an activated key pair.

  You can delete activated key pairs of encryption level 4 only. Activated key pairs of encryption level 3 are always needed by openUTM.

• Activate a previously created RSA key pair

  KC_ENCRYPT with subopcode1=KC_ACTIVATE_KEY causes an RSA key pair currently being used to be replaced by a RSA key pair created using KC_ENCRYPT, i.e. the next time a connection is established to an appropriately generated client, the public key of the new RSA key pair is transmitted to the client.

• Read a public key

  You can read the public key of an RSA key pair that was last created and that is not activated yet using KC_ENCRYPT subopcode1=KC_READ_NEW_PUBLIC_KEY. KC_ENCRYPT subopcode1=KC_READ_ACTIV_PUBLIC_KEY allows you to read the public key of an currently active RSA key pair.

  This function gives you added possibilities of increasing data security on your connection:

  In order for a client to be able to verify whether the public key received via the connection to the UTM application actually truly comes from that UTM application, you should read the public key, transfer it to the client using a different way and deposit it there.

  When the UTM application transmits the public key to the client the next time a connection is established, the client can compare the transmitted key with the one already stored.

  It is therefore advisable to transmit the public key of a newly created RSA key pair to all clients involved, i.e. all clients that support message encryption.

Transaction management / duration of effectiveness / cluster

Creating, activating and deleting a RSA key pair is subject to transaction management. You can create or activate a new key pair within a transaction. A new public key can only be read after the transaction is terminated.

The RSA key pair remains active until a new pair is created and activated or until the application is regenerated. In the event of regeneration, UTM automatically generates a new RSA key pair if the OPTION GEN-RSA-KEYS=YES statement is specified for the KDCDEF run (default setting).

The effect of the call persists beyond the current application run.

Reading the public key is not subject to transaction management.

The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies globally to the cluster, i.e.

• if you use the KC_ENCRYPT function to generate a new key pair at a node application then this key pair is also distributed to the other node applications so that all the node applications possess the same key pairs.

• if you activate or delete a previously generated key pair at a node application then this action is replicated at all the other node applications.

Data to be supplied

Function of the call	Data to be entered in the
	parameter area 1	identifications area	selection area	data area
Create RSA key pair	subopcode1: KC_CREATE_KEY subopcode2: encryption level	——	——	——
Delete non-activated RSA key pair	subopcode1: KC_DELETE_KEY subopcode2: encryption level	——	——	——
Delete activated RSA key pair	subopcode1: KC_DELETE_ACTIVE_KEY subopcode2: encryption level	——	——	——
Activate RSA key pair	subopcode1: KC_ACTIVATE_KEY subopcode2: encryption level	——	——	——
Public key of a not yet activated RSA key pair	subopcode1: KC_READ_NEW_PUBLIC_KEY subopcode2: encryption level	——	——	Pointer to a data area into which UTM can return the public key.
Public key of the currently active RSA key pair	subopcode1: KC_READ_ACTIV_PUBLIC_KEY subopcode2: encryption level	——	——	Pointer to a data area into which UTM can return the public key.

¹ In all cases, the operation code KC_ENCRYPT must be specified in the parameter area.

Parameter settings
Parameter area
Field name	Contents
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_ENCRYPT
subopcode1	KC_CREATE_KEY / KC_ACTIVATE_KEY / KC_DELETE_KEY/ KC_DELETE_ACTIVE_KEY / KC_READ_NEW_PUBLIC_KEY / KC_READ_ACTIV_PUBLIC_KEY
subopcode2	KC_ENC_LEV_3 / KC_ENC_LEV_4
obj_number	0
id_lth	0
select_lth	0
data_lth	length of data area / 0
Identification area
—
Selection area
—
Data area
—

KDCADMI call

KDCADMI (&parameter_area, NULL, NULL, NULL) or
KDCADMI (&parameter_area, NULL, NULL, &data_area)

Data returned by UTM
Parameter area
Field name	Field contents
retcode	return code
data_lth_ret	length of data returned/ 0
Data area
Data structure kc_encrypt_str / kc_encrypt_advanced_str / —

subopcode1

In the field subopcode1, you must specify which action UTM is to execute. You can enter the following subcodes:

KC_CREATE_KEY

Generates a new RSA key pair.

KC_ACTIVATE_KEY

Activates a RSA key pair created with KC_ENCRYPT.

KC_DELETE_KEY

Deletes a not yet activated RSA key pair.

KC_DELETE_ACTIVE_KEY

An activated RSA key pair is to be deleted. Only activated keys of encryption level 4 can be deleted.
This function is permitted only if the key pair has not been used by any object before deletion. It can be used, for example, after application regeneration and a subsequent KDCUPD to delete RSA keys that are no longer needed in the newly generated application.

KC_READ_NEW_PUBLIC_KEY

Reads the public key of a previously created and not yet activated RSA key pair.

KC_READ_ACTIV_PUBLIC_KEY

Reads the public key of the active RSA key pair.

subopcode2

In the field subopcode2, you must indicate to which encryption level the action specified in subopcode1 applies:

KC_ENC_LEV_3

The action applies for RSA keys with a key length of 1024 bits.

KC_ENC_LEV_4

The action applies for RSA keys with a key length of 2048 bits.

data_lth

In the field data_lth, you enter the following:

• with subopcode1=KC_CREATE_KEY, KC_DELETE_KEY, KC_DELETE_ACTIVE_KEY or KC_ACTIVATE_KEY:
  data_lth=0. When you call KDCADMI, you should pass the zero pointer to UTM for &data_area.

• with subopcode1=KC_READ_NEW_PUBLIC_KEY or KC_READ_ACTIV_PUBLIC_KEY:
  Length of the data area to which UTM is to return the public key of the RSA key pair. This data area must have the length of data structure kc_encrypt_advanced_str. For existing clients that work with subopcode2=KC_NO_SUBOPCODE, it must have the length of data structure kc_encrypt_str.
  When you call KDCADMI, you must pass the pointer to the data area to UTM.

retcode

In the field retcode, UTM supplies the return code of the call. Beside the return codes listed in section "Return codes", one of the following return codes can also occur:

Maincode = KC_MC_REJECTED

UTM rejected the call.

Subcode:

KC_SC_NO_ENCRYPTION

Encryption is not supported.

KC_SC_NEW_KEY_ALREADY_EXISTS

With subopcode1= KC_CREATE_KEY:
A new key pair has already been generated for this encryption level.

KC_SC_NO_NEW_KEY_EXISTS

With subopcode1=KC_READ_NEW_PUBLIC_KEY, KC_ACTIVATE_KEY, KC_DELETE_KEY:
There is no new key for the specified encryption level.

KC_SC_NO_ACTIV_KEY_EXISTS

With subopcode1= KC_READ_ACTIV_PUBLIC_KEY, KC_DELETE_ACTIVE_KEY:
There is no activated key for the specified encryption level.

KC_SC_IN_USE_DEL_NOT_ALLOWED

With subopcode1=KC_DELETE_ACTIVE_KEY:

• The key pair for the specified encryption level may not be deleted because it is required by at least one object.

• It is not permitted to delete a key pair of encryption Level 3 (this key pair is always needed by UTM).

KC_SC_NO_GLOB_CHANG_POSSIBLE

Only in UTM cluster applications:
No global administration changes are possible since the generation of the node applications is not consistent at present.
Action: Please try again later.

KC_SC_GLOB_CRE_DEL_LOCKED

Only in UTM cluster applications:
It is not possible to generate, delete or activate an RSA key pair at present because the generation or deletion of an object or the generation, deletion or activation of an RSA key pair has not yet been completed in a node application.
Action: Please try again later.

Maincode = KC_MC_RECBUF_FULL

Subcode:

KC_SC_NO_INFO

The buffer containing the restart information is full. (See openUTM manual “Generating
Applications”, KDCDEF control statement MAX, parameter RECBUF)

Maincode = KC_MC_REJECTED_CURR

The call cannot be processed at present.

Subcode:

KC_SC_INVDEF_RUNNING

Only in UTM cluster applications:
An inverse KDCDEF is currently running, i.e. the job cannot be processed at present.

data_lth_ret

data_lth_ret contains the data length returned to the data area by UTM.

• With subopcode1=KC_READ_NEW_PUBLIC_KEY and KC_READ_ACTIV_PUBLIC_KEY data_lth_ret != 0.
  If the value in data_lth_ret is smaller than the data area available (data_lth), the contents of the data area is only defined in data_lth_ret.

• In all other cases data_lth_ret=0

Data area

In the case where subopcode1=KC_READ_NEW_PUBLIC_ KEY or. KC_READ_ACTIV_PUBLIC_KEY, UTM returns the data structure kc_encrypt_advanced_str together with the public key of the specified encryption level. KC_READ_NEW_PUBLIC_KEY returns the key of the RSA key pair not yet activated. KC_READ_ACTIV_PUBLIC_KEY returns the key of the activated RSA key pair.

The data structure kc_encrypt_advanced_str is defined as follows:

struct kc_encrypt_advanced_str

char buf_lth[4];

char en_buffer[2048];

char en_key_lth[4];

The fields of the data structure have the following meanings:

buf_lth en_buffer en_key_lth

length of the data buffer en_buffer used. contains the public key that was read. length of the key (1024 or 2048).