Deploying a GREP11 server on IBM Secure Execution for Linux

1. Prepare GREP11 server image

Load the GREP11 server image from the tar archive. If you don't have the tar archive, see Downloading Crypto Express Network API for Secure Execution Enclaves.

Record the tag of the image, which is required to construct docker-compose.yml in Step 4.1.

docker load -i grep11server_s390x_1.1.2.1.tar

The following snippet shows an example of the output:

Loaded image: sys-hpcs-team-grep11-docker-local.artifactory.swg-devops.com/grep11-c16:grep11server_s390x-1.1.2.1

3. Prepare configuration files for GREP11 server

Prepare and collect the following files that are required for configuring the GREP11 server.

HSM domain values of c16server can be acquired from this step Configuring Crypto Express Card Domain.

Sample of grep11server.yaml:

#
# Copyright IBM Corp. All Rights Reserved.
#
# SPDX-License-Identifier: Apache-2.0
#
logging:
  # Package log levels
  # Levels: info, warning, debug, error, fatal, trace, and panic
  levels:
    # example below
    # entry: debug
###################################
## GRPC SERVICES TALKING TO GREP11 server ##
ep11crypto:
  enabled: true
  connection:
    address: 0.0.0.0
    port: 9876
    # Secure connection TLS options
    tls:
      enabled: true
      # certfile, keyfilie and cacert refer to the pem files that holds the certs
      certfile: /cfg/grep11-server.pem
      keyfile: /cfg/grep11-server.key
      mutual: true
      cacert: /cfg/grep11-ca.pem
      # same as above, but instead of filename, contents of PEM can be in an environment
      # variable (i.e. to avoid mounting files into docker container)
      cacertbytes:
      certfilebytes:
      keyfilebytes:
    # Server TCP/IP connection monitoring
    # serverKeepaliveTime is the duration in seconds after which if the server
    # does not see any activity from the client it pings the client to see
    # if it is alive
    # serverKeepaliveTimeout is the duration the server waits for a response
    # from the client after sending a ping before closing the connection
    keepalive:
      serverKeepaliveTime: 30
      serverKeepaliveTimeout: 5
  # A single card.domain tuple in hex
  # Example: "1.a" correspods 10th domain on the first card
  domain: "${C16SERVER_HSM_DOMAIN}"

Where Where C16SERVER_HSM_DOMAIN is a single card.domain tuple, e.g., "00.003a", that is configured on the c16server. A maximum of one domain is supported. In addition, only use the domain which has been granted access permission for the client. For more information, see Bind client certificate to target domain.

The following diagram shows the certificates that are used to configure the GREP11 server

Figure 1. Certificates to configure GREP 11 server

4. Deploy GREP11 server

4.1 Prepare docker-compose.yml

Prepare docker-compose.yml, which is used to boot up the GREP11 server container.

Note: You must change the image tag to grep11server image.

Sample of docker-compose.yml:

services:
  ep11server:
    user: "0"
    image: ${GREP11SERVER_IMAGE_TAG}
    ports:
      - 9876:9876
    volumes:
      - ./c16client.yaml:/etc/c16/c16client.yaml
      - ./c16-ca.pem:/cfg/c16server-ca.pem
      - ./c16-client.key:/cfg/c16server-client.key
      - ./c16-client.pem:/cfg/c16server-client.pem
      - ./grep11server.yaml:/etc/ep11server/ep11server.yaml
      - ./grep11-ca.pem:/cfg/grep11-ca.pem
      - ./grep11-server.pem:/cfg/grep11-server.pem
      - ./grep11-server.key:/cfg/grep11-server.key

Where GREP11SERVER_IMAGE_TAG is the grep11server image tag, like "us.icr.io/crypto-appliance/grep11server:s390x-1.1.2@sha256:54334c919a93c45f70d0252d8518d24b64255a88a073b35239f95d056d444ab8"

For single or multiple containers, you can also use the play subsection. In the play subsection, you can define the workload via Pod descriptors. Each pod can contain one or more container definitions. Descriptors can be provided as shown in the following example:

apiVersion: v1
kind: Pod
metadata:
  name: grep11server
spec:
  securityContext:
    privileged: true
  containers:
  - name: grep11server
    image: ${GREP11SERVER_IMAGE_TAG}
    volumeMounts:
    - name: c16-client
      mountPath: /etc/c16/c16client.yaml
    - name: c16-ca
      mountPath: /cfg/c16server-ca.pem
    - name: c16-client-key
      mountPath: /cfg/c16server-client.key
    - name: c16-client-pem
      mountPath: /cfg/c16server-client.pem
    - name: grep11-config
      mountPath: /etc/ep11server/ep11server.yaml
    - name: grep11-ca
      mountPath: /cfg/grep11-ca.pem
    - name: grep11-server-pem
      mountPath: /cfg/grep11-server.pem
    - name: grep11-server-key
      mountPath: /cfg/grep11-server.key
    securityContext:
      privileged: true
    ports:
    - containerPort: 9876
      hostPort: 9876
  volumes:
  - name: c16-client
    hostPath:
      path: ./c16client.yaml
      type: FileOrCreate
  - name: c16-ca
    hostPath:
      path: ./c16-ca.pem
      type: FileOrCreate
  - name: c16-client-key
    hostPath:
      path: ./c16-client.key
      type: FileOrCreate
  - name: c16-client-pem
    hostPath:
      path: ./c16-client.pem
      type: FileOrCreate
  - name: grep11-config
    hostPath:
      path: ./grep11server.yaml
      type: FileOrCreate
  - name: grep11-ca
    hostPath:
      path: ./grep11-ca.pem
      type: FileOrCreate
  - name: grep11-server-pem
    hostPath:
      path: ./grep11-server.pem
      type: FileOrCreate
  - name: grep11-server-key
    hostPath:
      path: ./grep11-server.key
      type: FileOrCreate
  restartPolicy: Always

Run the chmod 777 command on all the configuration files (c16-ca.pem, c16-client.key,c16-client.pem,grep11-ca.pem,grep11-server.pem,grep11-server.key).

4.2 Deploy GREP11 server container locally

You can deploy the GREP11 server container on a local s390x server by running the following command.

docker-compose up

You can deploy the GREP11 server container on a local s390x server using Podman, by running the following command.

podman play kube grep11.yaml

5. Test the workload

If you want to access cloud HSM on IBM Cloud Hyper Protect Crypto Services remotely to perform cryptographic operations, you need to generate a GREP11 API request in your on-prem environment to enable mutual TLS authentication for GREP11 API instead of IBM Cloud IAM authentication.

Prepare the following mutual TLS client certificates for connection with GREP11 server:

Add the following snippet into your code:

cert, _ := tls.LoadX509KeyPair("grep11-client.pem ", "grep11-client.key")
var callOpts = []grpc.DialOption{
  grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{Certificates: []tls.Certificate{cert}}))
}

Now you can perform cryptographic operations by remotely accessing the functions with the Enterprise PKCS #11 (EP11) over gRPC API calls. For more details, see Cryptographic operations: GREP11 API.