UC_AGENT_TLS_SETTINGS - Agent Certificate Management

To secure the communication, the server must be able to identify and authorize the agents. For this purpose, the Automation Engine automatically generates a public/private key pair and a self-signed certificate upon first startup.

However, you can use your own certificate authority. If you do so, make sure that the following extensions are set in your certificate:

  • Basic constraint: Subject Type = CA
  • Subject Key Identifier

This Variable (VARA) object allows you to customize the TLS/SSL settings for Agent authentication and file transfer and the respective key pair. UC_AGENT_TLS_SETTINGS is not supplied with the system and has to be created and configured in Client 0.

Important! When you modify a key relevant for the server certificate or the key pair, you must manually delete the respective files from the certificate folder (as defined in the CERTIFICATE_FOLDER key) before restarting the JWP. The files are generated with the new settings upon restarting the JWP.

The variable includes the following keys:

AGENT_CERTIFICATE_END_SPREAD

  • Description: Spread of the expiration point of the agent certificate in percentage

    This key allows you to set a time frame before the actual expiration of the agent certificate. The time frame is a percentage of the certificate's validity period. The actual expiration date is shifted randomly within this time frame, thus avoiding a period in which a large number of agent certificates expire at the same time.

  • Allowed values: Between 0 and 0.2 (inclusive)

  • Default value: 0.01 (1%)

    The default value is used if no value has been defined or if it does not comply with the allowed values.

  • Restart required: JWP

AGENT_CERTIFICATE_VALIDITY_DAYS

  • Description: Validity period of the agent certificate in days

    The validity period of the agent certificate cannot exceed the validity period of the AE certificate set in the key SERVER_CERTIFICATE_VALIDITY_DAYS.

    Note: This value can be modified using the key AGENT_CERTIFICATE_END_SPREAD.

  • Default value: 365

  • Restart required: JWP

CERTIFICATE_FOLDER

  • Description: AE folder in which server certificate and key pair are stored

  • Default value: ae-cert-management

  • Restart required: JWP

KEY_ALGORITHM

  • Description: Algorithm used for creating the key pair

  • Allowed values: RSA, DSA, ECDSA

  • Default value: RSA

    The default value is used if no value has been defined or if it does not comply with the allowed values.

  • Restart required: JWP

KEY_SIZE

  • Description: Key size used when generating the key pair

  • Allowed values: Elliptic curves for ECDSA

    • 256 (secp256k1)
    • 283 (sect283k1)
    • 409 (sect409r1)
    • 521 (p-521)
    • 571 (sect571k1)

  • Default value: RSA:4096, DSA:3072, ECDSA:256

    You cannot specify a smaller key size than the default size for each type.

    The default value is used if no value has been defined or if it does not comply with the allowed values.

  • Restart required: JWP

PRIVATE_KEY_FILENAME

  • Description: Name of the private server key

  • Default value: key

  • Restart required: JWP

PUBLIC_KEY_FILENAME

  • Description: Name of the public server key

  • Default value: key.pub

  • Restart required: JWP

SERVER_CERTIFICATE_COMMON_NAME

  • Description: Common name used to create the AE certificate

  • Default value: AE Agent Certificate

  • Restart required: JWP

SERVER_CERTIFICATE_END_MARGIN

  • Description: Period before the expiration of the AE certificate in percentage

    This key allows you to set a time frame before the actual expiration of the AE certificate. The time frame is a percentage of the certificate's validity period.

    When this margin is reached, the existing AE certificate and its corresponding key pair are deleted from the system and a new certificate is generated. However, the previous certificate remains in the UC_CERT table until its expiration date. The file transfer works normally during this period (until the certificate's actual expiration date).

  • Allowed values: Between 0 and 0.2 (inclusive)

  • Default value: 0.05 (5%)

    The default value is used if no value has been defined or if it does not comply with the allowed values.

  • Restart required: JWP

SERVER_CERTIFICATE_FILENAME

  • Description: Name of the AE certificate

  • Default value: intermediate.cert

  • Restart required: JWP

SERVER_CERTIFICATE_VALIDITY_DAYS

  • Description: Validity period of the AE certificate in days

  • Default value: 7300

  • Restart required: JWP

SIGNING_ALGORITHM

  • Description: Algorithm used for signing certificates

  • Allowed values: SHA256, SHA384, SHA512

  • Default value: SHA256

    The default value is used if no value has been defined or if it does not comply with the allowed values.

  • Restart required: JWP

See also: