Defining elliptic curve cryptographic schemes for a TLS client profile

You define the elliptic curve cryptographic schemes for a TLS client profile by using the developer toolkit CLI.

About this task

To define elliptic curve cryptographic schemes for a TLS client profile, you include elliptic_curve_auto_negotiation and elliptic_curve properties in a YAML file definition for the TLS client profile. The elliptic_curve property lists the required elliptic curve cryptographic schemes. For example:
elliptic_curve_auto_negotiation: false
elliptic_curve:
  - secp521r1
  - secp384r1
  - prime256v1

You then use the developer toolkit CLI to create the TLS client profile in API Connect.

When elliptic_curve_auto_negotiation is set to true, the system negotiates the Elliptic-curve Diffie-Hellman (ECDH) key agreement automatically with its peer, and any elliptic_curve property settings are ignored.

The following example shows a complete YAML file for a TLS client profile:
type: tls_client_profile
name: my-tls-client-profile
version: 1.0.0
title: My TLS client profile
protocols:
  - tls_v1.2
ciphers:
  - ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
elliptic_curve_auto_negotiation: false
elliptic_curve:
  - sect163k1
insecure_server_connections: false
server_name_indication: true
Note:
  • The elliptic_curve_auto_negotiation option is not supported by any of the API Connect gateway types. If the TLS client profile is targeted for an API Connect gateway; this setting is ignored by the gateway.
  • The elliptic curve cryptographic schemes shown in each row of the following table are equivalent. However, API Connect recognizes only one or the other depending on how the TLS profile is used, as indicated in the table.
    Table 1.
    API enforcement on the gateway API Connect server access security
    secp192r1 prime192v1
    secp256r1 prime256v1

    Therefore, if you want to use either of these schemes and are unsure whether you are targeting the TLS client profile to the API Connect gateway for API enforcement, whether you are using it to secure user access to the API Connect servers, or whether it will be used for both purposes, specify both equivalent schemes; API Connect will simply ignore the non-relevant scheme. For example:

    elliptic_curve:
       .
       .
       .
  - secp256r1
  - prime256v1
       .
       .
       .

Procedure

Complete the following steps to create a TLS client profile with elliptic curve cryptographic schemes defined:

  1. Create a YAML file definition for your TLS client profile, with the required elliptic_curve property.
  2. Log in to the management server from the developer toolkit CLI. Log in either as a member of the cloud administration organization or as a member of a provider organization, depending on where you want to create the TLS client profile. For details, see Logging in to a management server.
  3. Create the TLS client profile by using the following command: 
    apic tls-client-profiles:create --server mgmt_endpoint_url --org organization_name tls_client_profile_yaml_file
    where:
    • mgmt_endpoint_url is the platform API endpoint URL, and is the same as that which was used when you logged in at step 2.
    • organization_name is either admin, for the cloud administration organization, or the name of your provider organization, and is the same as that which was used when you logged in at step 2.
    • tls_client_profile_yaml_file is the name of the YAML file that contains the definition for your TLS client profile.
    Note: When you install IBM® API Connect, the API Connect gateway has a pre-supplied default TLS client profile that is used for API enforcement if you do not configure a TLS client profile; you cannot configure this default TLS client profile on the gateway.

    For reference details of all the apic tls-client-profiles commands, see the toolkit CLI reference documentation.

    You can also complete the operations described in this topic by using the API Connect REST APIs; see the API Connect REST API documentation.