Configuring Crypto Express Network API for Secure Execution Enclaves

Note: You must have ADMIN privileges to configure Crypto Express Network API for Secure Execution Enclaves.

Follow the instructions to configure Crypto Express Network API for Secure Execution Enclaves.

  1. Get an API token as access credential
  2. Get the Software license file
  3. Accept Software license and check acceptance status
  4. Check server status
  5. Configure Rsyslog client settings
  6. Generate mTLS server CSR and server KEY on server (openssl)
  7. Generate server certificate (openssl) with the generated server CSR to be assigned by CA ROOT
  8. Enable server with mTLS settings
  9. Manage the server
  10. Get domain list
  11. Bind client certificate to target domain
  12. Get server configurations

1. Get an API token as access credential

POST https://{{host}}/api/com.ibm.zaci.system/api-tokens HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0

{
    "kind": "request",
    "parameters": {
        "user": "<username>",
        "password": "<password>"
        }
}

Expected result:

{
  "kind": "response",
  "parameters": {
    "token": "<token>",
    "isAdmin": <true|false>
  }
}

Trouble Shooting:
* If you are not an admin, you cannot use any APIs of the Crypto Express Network API for Secure Execution Enclaves.
* An HTTP status code of 200 indicates a successful operation.
* If status code is not 200, ensure that you use the correct user/password of the web server in the Crypto Express Network API for Secure Execution Enclaves.

2. Get the Software license file

  • Get detailed content of the Software license in English:

    GET https://{{host}}/License/Lic_en.txt HTTP/1.1
    Content-Type: text/plain
    

    Expected result (content of the license file):

    LICENSE INFORMATION
    
    The Programs listed below are licensed under the following License Information terms and conditions in addition to the Program license terms previously agreed to by Client and IBM.
    ......
    
  • Get detailed content of non-IBM terms in English:

    GET https://{{host}}/License/non_ibm_license.txt HTTP/1.1
    Content-Type: text/plain
    

    Expected result (content of the license file):

    TERMS AND CONDITIONS FOR SEPARATELY LICENSED CODE
    
    Crypto Express Network API for Secure Execution Enclaves
    
    The IBM license agreement and any applicable information on the web
    download page for IBM products refers Licensee to this file for details
    concerning terms and conditions applicable to code identified as
    Separately Licensed Code below and included in the products listed
    above ("the Program").
    ......
    

3. Accept Software license and check acceptance status

After you review the Software license file, you can choose to accept or reject it with the following API request.

PUT https://{{host}}/api/com.ibm.zaci.system/software-license HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0

Accept with

{
    "kind": "request",
    "parameters": {
        "accept": true
    }
}

Reject with

{
    "kind": "request",
    "parameters": {
        "accept": false
    }
}

Expected result for accepting the license:

{
  "kind": "instance",
  "self": "/api/com.ibm.zaci.system/software-license",
  "resource-name": "software-license",
  "resource-version": "1.0",
  "properties": {
    "self": "/api/com.ibm.zaci.system/software-license",
    "accepted": true
  }
}

After you accept the Software license, you can use the following request to check the acceptance status.

GET https://{{host}}/api/com.ibm.zaci.system/software-license HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

4. Check server status

Use the request to get the server status.

GET https://{{host}}/api/com.ibm.crypto/server HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

If the server is configured, the following result is returned.

{
  "kind": "response",
  "parameters": {
    "msg": "Server is running.|| Server is stopped or failed to be started, more details please check logs."
  }
}

If server is fresh, the following result is returned.

{
  "kind": "response",
  "parameters": {
    "msg": "Fresh server, please config it firstly."
  }
}

Trouble Shooting:
* An HTTP status code of 200 indicates a successful operation.
* If status code is not 200, the web server on the Crypto Express Network API for Secure Execution Enclaves might be unavailable. Check the detailed error logs from the configured Rsyslog server, fix the error and retry the API.

If Rsyslog has been configured, you can see logs in the collected output. For example,

Jun 28 02:03:18 0 2022-06-28T06: 03:18.272572+00:00 hursscj cryptoapi-server-log - -  Analysis admin from token...
Jun 28 02:03:18 0 2022-06-28T06: 03:18.272797+00:00 hursscj cryptoapi-server-log - -  Receive a request from user - 'root' to check status of server.
Jun 28 02:03:18 0 2022-06-28T06: 03:18.272821+00:00 hursscj cryptoapi-server-log - -  Checking status of server...
Jun 28 02:03:18 0 2022-06-28T06: 03:18.275320+00:00 hursscj cryptoapi-server-log - -  Server is running.

If the request fails, you will get more details from the logs. For example,

Aug  7 23:40:27 0 2022-08-08T03: 40:27.873272+00:00 hursscj cryptoapi-server-log - -  Analysis admin from token...
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873576+00:00 hursscj cryptoapi-server-log - -  Receive a request from user - 'root' to restart server
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873586+00:00 hursscj cryptoapi-server-log - -  Validate request data of server API ...
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873620+00:00 hursscj cryptoapi-server-log - -  Request data of server API are valid.
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873644+00:00 hursscj cryptoapi-server-log - -  Analysis admin from token...
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873763+00:00 hursscj cryptoapi-server-log - -  Receive a request from user - 'root' to check status of server.
Aug  7 23:40:28 0 2022-08-08T03: 40:27.873783+00:00 hursscj cryptoapi-server-log - -  Checking status of server...
Aug  7 23:40:28 0 2022-08-08T03: 40:27.879243+00:00 hursscj cryptoapi-server-log - -  Server is stopped or failed to be started, more details please check logs.
Aug  7 23:40:28 0 2022-08-08T03: 40:27.879270+00:00 hursscj cryptoapi-server-log - -  Status of server is 768
Aug  7 23:40:28 0 2022-08-08T03: 40:27.879293+00:00 hursscj cryptoapi-server-log - -  restarting server...
Aug  7 23:40:28 0 2022-08-08T03: 40:28.075141+00:00 hursscj systemd 1 -  Started C16 Server Service.
Aug  7 23:40:28 0 2022-08-08T03: 40:28.075417+00:00 hursscj audit 1 -  SERVICE_START pid=1 uid=0 auid=4294967295 ses=4294967295 msg='unit=c16server comm="systemd" exe="/usr/lib/systemd/systemd" hostname=? addr=? terminal=? res=success'
Aug  7 23:40:28 0 2022-08-08T03: 40:28.210849+00:00 hursscj c16server 232057 -  [c16server][info] C16 Server starts ...
Aug  7 23:40:28 0 2022-08-08T03: 40:28.211257+00:00 hursscj c16server 232057 -  [c16server][debug] Preparing GRPC Server ...
Aug  7 23:40:28 0 2022-08-08T03: 40:28.213636+00:00 hursscj audit 232057 -  ANOM_ABEND auid=4294967295 uid=108 gid=999 ses=4294967295 pid=232057 comm="c16server" exe="/opt/zaas/c16server" sig=11 res=1
Aug  7 23:40:28 0 2022-08-08T03: 40:28.213713+00:00 hursscj c16server 232057 -  [c16server][info] c16server listening on: 0.0.0.0:9001
Aug  7 23:40:28 0 2022-08-08T03: 40:28.260934+00:00 hursscj systemd 1 -  c16server.service: Main process exited, code=dumped, status=11/SEGV
Aug  7 23:40:28 0 2022-08-08T03: 40:28.261069+00:00 hursscj systemd 1 -  c16server.service: Failed with result 'core-dump'.
Aug  7 23:40:28 0 2022-08-08T03: 40:28.261354+00:00 hursscj audit 1 -  SERVICE_STOP pid=1 uid=0 auid=4294967295 ses=4294967295 msg='unit=c16server comm="systemd" exe="/usr/lib/systemd/systemd" hostname=? addr=? terminal=? res=failed'
Aug  7 23:40:29 0 2022-08-08T03: 40:29.261253+00:00 hursscj event-daemon 19374 -  Processing '/var/run/event-daemon-out/core.c16server.232057.11'
Aug  7 23:40:29 0 2022-08-08T03: 40:29.261581+00:00 hursscj event-daemon 19374 -  Received message: err SELOG: 2A5A0092 11 ZFPC_SDK LOGCLASS:25 LOGTYPE:00 LOGACTION:0 LOGCOMPONENT:zfpc Process c16server.232057 core dumped (11).
Aug  7 23:40:30 0 2022-08-08T03: 40:30.078263+00:00 hursscj cryptoapi-server-log - -  Checking status of server again after restart...
Aug  7 23:40:30 0 2022-08-08T03: 40:30.078286+00:00 hursscj cryptoapi-server-log - -  Analysis admin from token...
Aug  7 23:40:30 0 2022-08-08T03: 40:30.078782+00:00 hursscj cryptoapi-server-log - -  Receive a request from user - 'root' to check status of server.
Aug  7 23:40:30 0 2022-08-08T03: 40:30.078803+00:00 hursscj cryptoapi-server-log - -  Checking status of server...
Aug  7 23:40:30 0 2022-08-08T03: 40:30.081310+00:00 hursscj cryptoapi-server-log - -  Server is stopped or failed to be started, more details please check logs.
Aug  7 23:40:30 0 2022-08-08T03: 40:30.081652+00:00 hursscj cryptoapi-server-log - -  9.46.32.199 - - [08/Aug/2022:03:40:30] "POST /api/com.ibm.crypto/server HTTP/1.1" 200 129 "" "vscode-restclient"
Aug  7 23:40:30 0 2022-08-08T03: 40:30.081871+00:00 hursscj cryptoapi-server-log - -  9.46.32.199 - - [08/Aug/2022:03:40:27 +0000] "POST /api/com.ibm.crypto/server HTTP/1.1" 200 381 "-" "vscode-restclient"

5. Configure Rsyslog client settings

Ensure that you have prepared the Rsyslog server for log collection. Proceed to the following steps to send logs from Crypto Express Network API for Secure Execution Enclaves to the Rsyslog server.

POST https://{{host}}/api/com.ibm.crypto/apilog
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
{
    "kind":"request",
    "parameters":{
      "rsyslog_config":{
           "rsyslog_ca_root": "<rsyslog server CA ROOT in BASE64, the same CA ROOT in section 'Prepare Rsyslog server for log  collection'>",
           "rsyslog_client_cert": "<rsyslog client certificate in BASE64>",
           "rsyslog_client_key": "<rsyslog client key in BASE64>",
           "rsyslog_server_ip": "<IP of rsyslog server>"
      },
      "c16server_log_config":{
          "loglevel": "info(default)|debug|trace|warn|err|error|critical|off"
        }
    }
}

Note: rsyslog_ca_root is the ROOT certificate of the Rsyslog server that you configured in Preparing Rsyslog server for log collection. Use the following command to encode your certificate by using BASE64:

base64 rsyslog-ca.pem -w 0

You can set loglevel to trace, debug, info, warn, err, error, critical, or off. info is default value.

Expected result:

{
  "kind": "response",
  "parameters": {
    "msg": "Success to process log settings of Rsyslog client and C16server"
  }
}

Trouble Shooting:
* An HTTP status code of 200 indicates a successful operation.
* If status code is not 200, the web server on the Crypto Express Network API for Secure Execution Enclaves might be unavailable. Check the detailed error logs from the configured Rsyslog server, fix the error and retry the API.
* If returns format error messages, input the parameters in the correct format.
* If you don't receive logs from the Rsyslog server, see Preparing Rsyslog server for log collection.

If the Rsyslog settings are configured successfully, the API logs will be sent to the Rsyslog server and recorded into rsyslog log files. For example,

Jun 28 01:36:58 0 2022-06-28T05: 36:58.021041+00:00 hursscj cryptoapi-logset-log - -  Analysis admin from token...
Jun 28 01:36:58 0 2022-06-28T05: 36:58.021337+00:00 hursscj cryptoapi-logset-log - -  Receive a request from user - 'root' to set log configurations for server.
Jun 28 01:36:58 0 2022-06-28T05: 36:58.021365+00:00 hursscj cryptoapi-logset-log - -  Validate request data of apilog API ...
Jun 28 01:36:58 0 2022-06-28T05: 36:58.021392+00:00 hursscj cryptoapi-logset-log - -  set loglevel to 'debug'
Jun 28 01:36:58 0 2022-06-28T05: 36:58.021418+00:00 hursscj cryptoapi-logset-log - -  Request data of apilog API are valid.
Jun 28 01:36:58 0 2022-06-28T05: 36:58.023964+00:00 hursscj cryptoapi-logset-log - -  Update CA root of rsyslog collection by user - 'root'.
Jun 28 01:36:59 0 2022-06-28T05: 36:58.382255+00:00 hursscj cryptoapi-logset-log - -  Success to update configurations of log collection by user - 'root'.
Jun 28 01:36:59 0 2022-06-28T05: 36:58.382899+00:00 hursscj cryptoapi-logset-log - -  9.46.32.199 - - [28/Jun/2022:05:36:58] "POST /api/com.ibm.crypto/apilog HTTP/1.1" 200 99 "" "vscode-restclient"
Jun 28 01:36:59 0 2022-06-28T05: 36:58.383222+00:00 hursscj cryptoapi-logset-log - -  9.46.32.199 - - [28/Jun/2022:05:36:58 +0000] "POST /api/com.ibm.crypto/apilog HTTP/1.1" 200 411 "-" "vscode-restclient"

6. Generate mTLS server CSR and server KEY on server

The following API generates the server KEY and certificate signing request (CSR) for the server, which will be used to enable mTLS on server side. The CSR will be returned to admin and used to issue a server certificate by Client CA.

POST https://{{host}}/api/com.ibm.crypto/csr
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0
{
    "kind":"request",
    "parameters":{
        "mtls":{
            "server_common_name":"<IP/DNS of c16 server>"
        }
    }
}

Expected result:

{
  "kind": "response",
  "parameters": {
    "msg": "Success to generate mTLS server KEY and server CSR by user - 'root'",
    "server_csr": "<c16server CSR which is encoded with BASE64 encoded>"
  }
}

Note: Decode server_csr before the next step by using the following command:

echo server_csr|base64 -d

Trouble Shooting:
* An HTTP status code of 200 indicates a successful operation.
* If status code is not 200, the web server on the Crypto Express Network API for Secure Execution Enclaves might be unavailable. Check the detailed error logs from the configured Rsyslog server, fix the error and retry the API.
* If returns format error messages, input the parameters in the correct format.
* If returns generation error messages, get the logs and contact your system administrator.

If the request succeeds, you can check the result in the rsyslog file:

Jun 28 01:42:14 0 2022-06-28T05: 42:14.623579+00:00 hursscj cryptoapi-csr-log - -  Analysis admin from token...
Jun 28 01:42:14 0 2022-06-28T05: 42:14.623871+00:00 hursscj cryptoapi-csr-log - -  Receive a request from user - 'root' to generate mTLS server KEY and server CSR.
Jun 28 01:42:14 0 2022-06-28T05: 42:14.623896+00:00 hursscj cryptoapi-csr-log - -  Validate request data of csr API ...
Jun 28 01:42:14 0 2022-06-28T05: 42:14.624857+00:00 hursscj cryptoapi-csr-log - -  Request data of csr API are valid.
Jun 28 01:42:14 0 2022-06-28T05: 42:14.624883+00:00 hursscj cryptoapi-csr-log - -  Generate mTLS server KEY and server CSR for user - 'root'...
Jun 28 01:42:14 0 2022-06-28T05: 42:14.628669+00:00 hursscj cryptoapi-csr-log - -  Generating RSA private key, 2048 bit long modulus (2 primes)
Jun 28 01:42:14 0 2022-06-28T05: 42:14.669785+00:00 hursscj cryptoapi-csr-log - -  .......................+++++
Jun 28 01:42:14 0 2022-06-28T05: 42:14.710054+00:00 hursscj cryptoapi-csr-log - -  ......................+++++
Jun 28 01:42:14 0 2022-06-28T05: 42:14.710188+00:00 hursscj cryptoapi-csr-log - -  e is 65537 (0x010001)
Jun 28 01:42:14 0 2022-06-28T05: 42:14.716938+00:00 hursscj cryptoapi-csr-log - -  Success to generate mTLS server KEY and server CSR by user - 'root'.
Jun 28 01:42:14 0 2022-06-28T05: 42:14.717827+00:00 hursscj cryptoapi-csr-log - -  9.46.32.199 - - [28/Jun/2022:05:42:14] "POST /api/com.ibm.crypto/csr HTTP/1.1" 200 1448 "" "vscode-restclient"
Jun 28 01:42:14 0 2022-06-28T05: 42:14.718113+00:00 hursscj cryptoapi-csr-log - -  9.46.32.199 - - [28/Jun/2022:05:42:14 +0000] "POST /api/com.ibm.crypto/csr HTTP/1.1" 200 1762 "-" "vscode-restclient"

If the request fails, you can check for errors from the returned message directly or find more details in the Rsyslog file.

7. Generate server certificate (openssl) with the generated server CSR to be assigned by CA ROOT

Use your enterprise CA to issue a c16server certificate based on the returned CSR in Step 6.

Prepare the following certificates for mTLS connection:

Filename Description
c16server-ca.pem c16server CA root certificatein a file called req.json.
c16server-ca.key c16server CA root key

If you have already prepared the CA root, complete the following steps:

The following diagram is shows the flow of how to configure mTLS of the C16 server.

Configure mTLS Figure 1. Configuring mTLS of C16 server

8. Enable server with mTLS settings

Configure mTLS settings of c16 server. If you need to reconfigure mTLS of c16 server, use this API to refresh c16 server CA root and c16 server certificate.

Prepare the following certificates for mTLS connection:

Filename Description
c16server-ca.pem c16server CA root certificate (Used as CA root on c16server side in mTLS connection.)
c16server-cert.pem c16server mTLS server certificate, which is issued by c16server CA root based on server.csr in step6. (Generated by step7, used as mTLS server certificate on c16server side in mTLS connection.)
POST https://{{host}}/api/com.ibm.crypto/configs HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0

{
    "kind":"request",
    "parameters":{
        "mtls":{
            "client_ca_root": "<BASE64 of c16server-ca.pem, c16server CA root>",
            "server_cert":"<BASE64 of c16server-cert.pem, which is issued on Step7.>"
        }
    }
}

Expected result:

{
  "kind": "response",
  "parameters": {
    "msg": "Server is configured with mTLS successfully by user - 'root'."
  }
}

Trouble Shooting:
* An HTTP status code of 200 indicates a successful operation.
* If status code is not 200, the web server on the Crypto Express Network API for Secure Execution Enclaves might be unavailable. Check the detailed error logs from the configured Rsyslog server, fix the error and retry the API.
* If returns format error messages, ensure that the client root certificate and server certificate used are correct and encoded by using base64.
* If returns "Failed to store configurations" or you see execution error messages, get the logs and contact your system administrator.

If the request succeeds, check the rsyslog file for logs where state server settings are updated.

Jun 28 01:53:05 0 2022-06-28T05: 53:05.302427+00:00 hursscj cryptoapi-configs-log - -  Analysis admin from token...
Jun 28 01:53:05 0 2022-06-28T05: 53:05.302612+00:00 hursscj cryptoapi-configs-log - -  Receive a request from user - 'root' to enable mTLS for server.
Jun 28 01:53:05 0 2022-06-28T05: 53:05.302638+00:00 hursscj cryptoapi-configs-log - -  Validate request data of configs API ...
Jun 28 01:53:05 0 2022-06-28T05: 53:05.302692+00:00 hursscj cryptoapi-configs-log - -  Request data of configs API are valid.
Jun 28 01:53:05 0 2022-06-28T05: 53:05.311498+00:00 hursscj cryptoapi-configs-log - -  Success to update server settings by user - 'root'.
Jun 28 01:53:05 0 2022-06-28T05: 53:05.311925+00:00 hursscj cryptoapi-configs-log - -  9.46.32.199 - - [28/Jun/2022:05:53:05] "POST /api/com.ibm.crypto/configs HTTP/1.1" 200 108 "" "vscode-restclient"
Jun 28 01:53:05 0 2022-06-28T05: 53:05.312138+00:00 hursscj cryptoapi-configs-log - -  9.46.32.199 - - [28/Jun/2022:05:53:05 +0000] "POST /api/com.ibm.crypto/configs HTTP/1.1" 200 432 "-" "vscode-restclient"

Note: You might modify mTLS configurations through this REST API to use a new CA cert for c16 to block or revoke access of c16 API from a particular client. This blocks the accesses from all clients that are using client certificate, which the previous CA issued. All clients that need access to the c16 API need to be reconfigured with a new client cert that the new CA issues.

9. Manage the server

After you configure the server with previous steps, start or restart the server and check its status.

  • For a fresh server, set action to start in the following API request.
  • For a reconfigured server, set action to restart.
POST https://{{host}}/api/com.ibm.crypto/server HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0
Content-type: application/vnd.ibm.zaci.payload+json;version=1.0

{
    "kind":"request",
    "parameters":{
        "action": "start"
    }
}

You can tell from the results whether the server is configured successfully with paired certificates or fails to be started.

{
  "kind": "response",
  "parameters": {
    "msg": "Server starts successfully by user - 'root'. || Server fails to be started by user - 'root', please check logs for more details."
  }
}

The following table shows admin operation, server status, and the corresponding message.

Condition Administrator Operation Server Status Message
Cond1 Start start "Server is running, start action will not be done."
Cond2 Stop stop "Server is not running, please use other actions to operate server."
Cond3 Start not configured yet "Please use /configs API to config server firstly."
Cond4 Restart
"Server restarts successfully." or "Server fails to be restarted, please check logs for more details."

Expected logs with the operation to restart server:

Jun 28 02:01:22 0 2022-06-28T06: 01:21.763873+00:00 hursscj systemd 1 -  Stopping C16 Server Service...
Jun 28 02:01:22 0 2022-06-28T06: 01:21.764404+00:00 hursscj systemd 1 -  c16server.service: Succeeded.
Jun 28 02:01:22 0 2022-06-28T06: 01:21.764680+00:00 hursscj audit 1 -  SERVICE_STOP pid=1 uid=0 auid=4294967295 ses=4294967295 msg='unit=c16server comm="systemd" exe="/usr/lib/systemd/systemd" hostname=? addr=? terminal=? res=success'
Jun 28 02:01:22 0 2022-06-28T06: 01:21.765949+00:00 hursscj audit 1 -  SERVICE_START pid=1 uid=0 auid=4294967295 ses=4294967295 msg='unit=c16server comm="systemd" exe="/usr/lib/systemd/systemd" hostname=? addr=? terminal=? res=success'
Jun 28 02:01:22 0 2022-06-28T06: 01:21.768942+00:00 hursscj c16server 30329 -  [c16server][info] C16 Server starts ...
Jun 28 02:01:22 0 2022-06-28T06: 01:21.769203+00:00 hursscj c16server 30329 -  [c16server][debug] Preparing GRPC Server ...
Jun 28 02:01:22 0 2022-06-28T06: 01:21.771361+00:00 hursscj c16server 30329 -  [c16server][info] c16server listening on: 0.0.0.0:6000
Jun 28 02:01:22 0 2022-06-28T06: 01:21.764636+00:00 hursscj systemd 1 -  Stopped C16 Server Service.
Jun 28 02:01:22 0 2022-06-28T06: 01:21.765819+00:00 hursscj systemd 1 -  Started C16 Server Service.
Jun 28 02:01:23 0 2022-06-28T06: 01:23.769305+00:00 hursscj cryptoapi-server-log - -  Checking status of server again after restart...
Jun 28 02:01:23 0 2022-06-28T06: 01:23.769335+00:00 hursscj cryptoapi-server-log - -  Analysis admin from token...
Jun 28 02:01:23 0 2022-06-28T06: 01:23.769848+00:00 hursscj cryptoapi-server-log - -  Receive a request from user - 'root' to check status of server.
Jun 28 02:01:23 0 2022-06-28T06: 01:23.769865+00:00 hursscj cryptoapi-server-log - -  Checking status of server...
Jun 28 02:01:23 0 2022-06-28T06: 01:23.772901+00:00 hursscj cryptoapi-server-log - -  Server is running.
Jun 28 02:01:23 0 2022-06-28T06: 01:23.772925+00:00 hursscj cryptoapi-server-log - -  Server restarts successfully by user - 'root'.
Jun 28 02:01:23 0 2022-06-28T06: 01:23.773266+00:00 hursscj cryptoapi-server-log - -  9.46.32.199 - - [28/Jun/2022:06:01:23] "POST /api/com.ibm.crypto/server HTTP/1.1" 200 93 "" "vscode-restclient"
Jun 28 02:01:23 0 2022-06-28T06: 01:23.773474+00:00 hursscj cryptoapi-server-log - -  9.46.32.199 - - [28/Jun/2022:06:01:21 +0000] "POST /api/com.ibm.crypto/server HTTP/1.1" 200 416 "-" "vscode-restclient"

10. Get domain list

GET module.domain list of located system via API /api/com.ibm.crypto/domains:GET, and save the name of the target domain.

11. Bind client certificate to target domain

Get c16 client certificate ready which is generated via prepare mTLS cert.

Bind c16 client certificate to target domain via API /api/com.ibm.crypto/domains/${module_id}.${domain_id}:POST.

12. Get server configurations

You can review your configurations of the c16 server with the following API request, and you can confirm if the domains have been bound with the client.

GET https://{{host}}/api/com.ibm.crypto/configs HTTP/1.1
zACI-API: com.ibm.zaci.system/1.0
Authorization: Bearer {{login.response.body.parameters.token}}
Accept: application/vnd.ibm.zaci.payload+json;version=1.0

Expected result:

{
  "kind": "collection",
  "self": "/api/com.ibm.crypto/configs",
  "resource-name": "configs",
  "resource-version": "1.0",
  "instances": {
    "mtls": {
      "client_ca_root": "<c16server-ca.pem, CA ROOT in BASE64>",
      "server_cert": "<c16server-cert.pem, c16Server certificate in BASE64>"
    },
    "rsyslog_config": {
      "rsyslog_ca_root": "<CA ROOT in BASE64>",
      "rsyslog_client_cert": "<Server certificate in BASE64>",
      "rsyslog_server_ip": "<rsyslog Server ip>",
    },
    "c16server_log_config": {
      "loglevel": "<LOGLEVEL>"
    },
    "c16server_client_ACL": {
      "enableClientACL": "<boolean>"
    },
    "ilmt": {
      "server": "<hostname of ilmt server>"
    },
    "ca_monitor": {
      "username": "<Username for CA monitor authentication>",
      "password_hash": "<password for CA monitor authentication, encode by Base64>",
      "tls_cert":"<TLS certificate for CA monitor, encode by Base64>",
      "tls_key":"<TLS key for CA monitor, encode by Base64>"
    }
  }
}

You can also get the configurations from the rsyslog file.

Jun 16 02:07:27 0 2022-06-16T06: 07:27.145026+00:00 hursscj cryptoapi-configs-log - -  9.200.37.244 - - [16/Jun/2022:06:07:27 +0000] "GET /api/com.ibm.crypto/configs HTTP/1.1" 401 432 "-" "vscode-restclient"
Jun 16 02:07:36 0 2022-06-16T06: 07:36.110993+00:00 hursscj cryptoapi-configs-log - -  Receive a request to get server configurations
Jun 16 02:07:36 0 2022-06-16T06: 07:36.111607+00:00 hursscj cryptoapi-configs-log - -  Success to fetch server configurations : {'mtls': {'client_ca_root': '<CA ROOT in BASE64>', 'server_cert': '<Server certificate in BASE64>'}, 'log_config': {'ld_ca_root': '<Rsyslog server CA ROOT in BASE64>', 'log_target_ip': '9.47.152.179', 'logdna_key': ''}}
Jun 16 02:07:36 0 2022-06-16T06: 07:36.111943+00:00 hursscj cryptoapi-configs-log - -  9.200.37.244 - - [16/Jun/2022:06:07:36] "GET /api/com.ibm.crypto/configs HTTP/1.1" 200 6959 "" "vscode-restclient"
Jun 16 02:07:36 0 2022-06-16T06: 07:36.112171+00:00 hursscj cryptoapi-configs-log - -  9.200.37.244 - - [16/Jun/2022:06:07:36 +0000] "GET /api/com.ibm.crypto/configs HTTP/1.1" 200 7284 "-" "vscode-restclient"

Notes:

  1. All certificate related parameters should be encoded by using BASE64. Use following command to encode:
base64 rsyslog-ca.pem -w 0
  1. If you want to verify the content of the BASE64 string or decode returned server CSR, use the following command to decode:
echo server_csr|base64 -d