API endpoints

The following documentation provides specifications for the API operations to configure and manage the c16 server.

Note: All the REST APIs can be accessed only by the ADMIN role.

/api/com.ibm.crypto /apilog:POST

Configure Rsyslog server and set loglevel of the c16 server.

The endpoint accepts request in JSON and returns a response in JSON. You can modify the apilog endpoint with the following parameters:

  • rsyslog_ca_root

    Specify rsyslog server CA ROOT in BASE64, the same CA ROOT in section 'Prepare Rsyslog server for log collection

  • rsyslog_client_cert

    Specify rsyslog client certificate in BASE64.

  • rsyslog_client_key

    Specify rsyslog client key in BASE64

  • rsyslog_server_ip

    Specify IP of rsyslog server

  • c16server_log_config

    Specify the log level of the c16 server to info, debug, trace, warn, err, error, critical, off, with info by default.

The following example shows how to specify these parameters:

{
    "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": "error(default)|debug|trace|warn|err|error|critical|off"
        }
    }
}

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/apilog -X POST -d@apilog.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

The following example shows how to define the apilog parameters and the response that is returned.

Step 1. Define the apilog parameters in a file named apilog.json.

{
    "kind":"request",
    "parameters":{
        "log_config":{
            "ld_ca_root": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUduRENDQlFTZ0F3SUJBZ0lVQTdmeGpycjdRNTZZdTUrc0pWbGFsbDdxVmxNd0RRWUpLb1pJaHZjTkFRRUwKQlFBd2dnRWFNUlV3RXdZRFZRUURFd3c1TGpRM0xqRTFNaTR4TnpreEV6QVJCZ29Ka2lhS…",
            "log_target_ip": "9.123.23.222",
            "loglevel": "error"
        }
    }
}

Step 2. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/apilog -X POST -d@apilog.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

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

/api/com.ibm.crypto /csr:POST

Generate c16 server mTLS on the server side, server KEY and server CSR, and return the server CSR to the user. The server CSR must be assigned by custom CA root to generate the server certificate.

The endpoint accepts request in JSON and returns a response in JSON. You can modify the csr endpoint with the following parameter:

  • server_common_name

    Specify the IP/DNS value of the LPAR that is installed with Crypto Express Network API for Secure Execution Enclaves.

The following example shows how to specify these parameters:

{
    "kind":"request",
    "parameters":{
        "mtls":{
            "server_common_name": <IP/DNS value of the LPAR which installed with Crypto Express Network API for Secure Execution Enclaves>
        }
    }
}

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/csr -X POST -d@csr.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

The following example shows how to define the csr parameters and the response that is returned.

Step 1. Define the csr parameters in a file named csr.json.

{
    "kind":"request",
    "parameters":{
        "mtls":{
            "server_common_name": "9.22.32.121"
        }
    }
}

Step 2. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/csr -X POST -d@csr.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

{
  "kind": "response",
  "parameters": {
"msg": "Success to generate mTLS server KEY and server CSR by user - 'root'",
    "server_csr": "LS0tLS1CRUdJTiBDR… "
  }
}

/api/com.ibm.crypto/configs:POST

Configure mTLS certificates for the c16 server.

The endpoint accepts request in JSON and returns a response in JSON. You can modify the configs endpoint with the following parameters:

  • client_ca_root

    Specify the CA root certificate with base64 encoding that is used to issue the server or client certificate.

  • server_cert

    Specify the server certificate that is issued by the client CA certificate based on the server CSR.

The following example shows how to specify these parameters:

{
    "kind":"request",
    "parameters":{
        "mtls":{
            "client_ca_root": "<base64 of CA root>",
            "server_cert":"<BASE64 of server.pem which is issued by CA root by customer>"
        }
    }
}

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/configs -X POST -d@configs.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

The following example shows how to define the configs parameters and the response that is returned.

Step 1. Define the configs parameters in a file named configs.json.

{
    "kind":"request",
    "parameters":{
        "mtls":{
            "client_ca_root": "LS0tLS1CRUdJTiBDR…",
            "server_cert":"LS0tLS2STBJJDKED"
        }
    }
}

Step 2. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/configs -X POST -d@configs.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

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

/api/com.ibm.crypto /configs:GET

Get configurations of mTLS certificates for the c16 server.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/configs -X -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

The following example shows how to get the configs settings.

Step 1. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/configs -X GET -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

{
  "kind": "collection",
  "self": "/api/com.ibm.crypto/configs",
  "resource-name": "configs",
  "resource-version": "1.0",
  "instances": {
    "mtls": {
      "client_ca_root": "<CA ROOT in BASE64>",
      "server_cert": "<Server 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>"
    }
  }
}

/api/com.ibm.crypto /server:POST

Manage the c16 server.

The endpoint accepts request in JSON and returns a response in JSON. You can modify the server endpoint with the following parameter:

  • action

    Specify the actions to be done on the c16 server, including start, restart, or stop.

The following example shows how to specify these parameters:

{
    "kind":"request",
    "parameters":{
        "action": "start|restart|stop"
    }
}

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/server -X POST -d@configs.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

The following example shows how to define the server parameters and the response that is returned.

Step 1. Define the server parameters in a file named server.json.

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

Step 2. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/server -X POST -d@configs.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

  • If the server fails to be started or restarted, the following response is returned:

    {
    "kind": "response",
    "parameters": {
        "msg": "Server starts successfully by user - 'root'. || Server fails to be started by user - 'root', please check logs for more details."
    }
    }
    
  • If the server is successfully started or restarted, the following response is returned:

    {
    "kind": "response",
    "parameters": {
        "msg": "Server is started|restarted successfully by user – 'root'.
    "
    }
    }
    

/api/com.ibm.crypto /server:GET

Check status of the c16 server.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/server -X -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

The following example shows how to get the server settings.

Step 1. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/server -X GET -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

  • If the server is running, the following response is returned:

    {
    "kind": "response",
    "parameters": {
        "msg": "Server is running."
    }
    }
    
  • If the server fails, the following response is returned:

    {
    "kind": "response",
    "parameters": {
        "msg": "Server is stopped or failed to be started, more details please check logs."
    }
    }
    
  • If the server hasn’t been configured, the following response is returned:

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

/api/com.ibm.crypto/ilmt:GET

Get the scan reports of IBM License Metric Tool.

The endpoint accepts request in JSON and returns IBM License Metric Tool scan reports as tar.gz.

Synopsis of the request URL:

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/ilmt -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>" --output ilmt_scanlog.tar.gz

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

The following example shows how to use CURL to request and download IBM License Metric Tool scan reports in the tar.gz.

Step 1. Submit the request.

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/ilmt -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>" --output ilmt_scanlog.tar.gz

Returned response

IBM License Metric Tool scan reports are patched as tar.gz. You can use the request command to download those reports with the name of ilmt_scanlog.tar.gz and extract the tar.gz to get all IBM License Metric Tool scan reports.

/api/com.ibm.crypto/ilmt:POST

Bind IBM License Metric Tool server to post the scan reports once they're generated.

The endpoint accepts request in JSON and returns upload status.

Supported request types and response formats

Supported request types:

  • JSON

Supported response formats:

  • JSON

Example

Step 1. Define the csr parameters in a file called req.json.

{
   "kind": "request",
   "parameters":{
      "server": "${lmtserver}",
      "token": "${lmttoken}"
   }
}

Step 2. Submit request

curl -k -X POST https://${server_ip}/api/com.ibm.crypto/ilmt  -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}" -d@req.json

Returned response

{
  "kind": "response",
  "parameters": {
    "success": false,
    "message": "the configuration is done successfully"
  }
}

/api/com.ibm.zaci.system/appliance-configuration/export:POST

Export data of current appliance.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X POST https://${src_server_ip}/api/com.ibm.zaci.system/appliance-configuration/export -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/octet-stream' -H "Authorization: Bearer ${auth_token}" -d@req.json -o ${export_description}.data

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Define the csr parameters in a file called req.json.

{
   "kind": "request",
   "parameters":{
      "description":"<description>"
   }
}

Step 2. Submit request

curl -k -X POST https://${src_server_ip}/api/com.ibm.zaci.system/appliance-configuration/export -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/octet-stream' -H "Authorization: Bearer ${auth_token}" -d@req.json -o ${export_description}.data

/api/com.ibm.zaci.system/appliance-configuration/import?apply_now=false:POST

Import data of previous appliance.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X POST https://${dst_server_ip}/api/com.ibm.zaci.system/appliance-configuration/import?apply_now=false -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/octet-stream' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}" -T ./${export_description}.data

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Get the previous exported data ready

Step 2. Submit request

curl -k -X POST https://${dst_server_ip}/api/com.ibm.zaci.system/appliance-configuration/import?apply_now=false -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/octet-stream' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}" -T ./${export_description}.data

Returned response

{
  "kind": "instance",
  "self": "/api/com.ibm.zaci.system/appliance-configuration/import",
  "resource-name": "appliance-configuration",
  "resource-version": "1.0",
  "properties": {
    "name": "crypto_appliance",
    "description": "<description>",
    "created": "Thu Jul 20 08:10:34 2023"
  }
}

/api/com.ibm.zaci.system/appliance-configuration:PUT

Trigger to restore after import data of previous appliance.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X PUT https://<crypto_appliance_host>/api/com.ibm.zaci.system/appliance-configuration -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json; version = 1.0' -H "Authorization: Bearer <token>"

Supported request types and response formats

Supported request types:

  • PUT

Supported response formats:

  • JSON

Example

Step 1. Submit request

curl -k -X PUT https://${dst_server_ip}/api/com.ibm.zaci.system/appliance-configuration -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json; version = 1.0' -H "Authorization: Bearer ${auth_token}"

/api/com.ibm.crypto/domains/enableClientACL=true:POST

Enable ordDisable management of client-domain bindings, with default setting as 'Enable'

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -H POST https://${dst_server_ip}/api/com.ibm.crypto/domains/enableClientACL=true -X POST -d@req.json -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json;version=1.0' -H "Authorization: Bearer ${auth_token}"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Prepare the req.json file

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

Step 2. Submit request

curl -k -H PUT https://${dst_server_ip}/api/com.ibm.crypto/domains/enableClientACL=true  -X POST -d@req.json -H 'zACI-API: com.ibm.zaci.system/1.0'  -H 'Content-type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json; version = 1.0' -H "Authorization: Bearer ${auth_token}"

/api/com.ibm.crypto/domains:GET

GET module.domain list of located system, includes all types domains, eg. CONTROL, BOTH.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/domains -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>"

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

Step 1. Submit request

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/domains -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>"

Returned response

{
  "kind": "response",
  "parameters": [
    {
        "${module_id_1}.${domain_id_1}((BOTH))":
        {
            "client1_fingerprint":
            {
                "x509_pem_cert":"<base64 of client1 pem>",
                "x509_common_name":"common name of client1 server"
            }
        },
        "${module_id_2}.${domain_id_2}(CONTROL)":
        {
            "client2_fingerprint":
            {
                "x509_pem_cert": "<base64 of client2 pem>",
                "x509_common_name": "common name of client2 server"   
            }
        }
    }]
}

/api/com.ibm.crypto/domains/${module_id_1}.${domain_id_1}:GET

GET the binding status of target module.domain.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/domains/${module_id_1}.${domain_id_1} -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

Step 1. Submit request

curl -k -X GET https://<crypto_appliance_host>/api/com.ibm.crypto/domains -H "Accept: application/octet-stream" -H "zACI-API: com.ibm.zaci.system/1.0" -H "Authorization: Bearer <token>"

Returned response

{
  "kind": "response",
  "parameters": [
    "${module_id_1}.${domain_id_1}(BOTH)":
    {
        "client1_fingerprint":
        {
            "x509_pem_cert": "<base64 of client1 pem>",
            "x509_common_name": "common name of client1 server" 
        }
    }
  ]
}

/api/com.ibm.crypto/domains/${module_id}.${domain_id}:POST

Bind a client certificate to a target domain.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/domains/${module_id}.${domain_id} -X POST -d@client.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Get the client certificate ready in the client.json file.

[
  {
    "client_pem": "<client's certificate for connection with c16server in Base64>"
  }
]

Step 2. Submit request

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/domains/${module_id}.${domain_id} -X POST -d@client.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

If the binding is successful, returns all bound relationships with target module_id.domain_id.

{
  "kind": "response",
  "parameters": [
    "${module_id_1}.${domain_id_1}":
    {
        "client1_fingerprint":
        {
            "x509_pem_cert": "<base64 of client1 pem>",
            "x509_common_name": "common name of client1 server"
        }
    }
  ]
}

If failed to bind:
[
  {
    'message': 'Current client certificate has been binded with target <module_id>.<domain_id>. | One client certificate had been binded with Module_id.Domain_id. If you want to bind with this client, please delete the old binding firstly.'
  }
]

/api/com.ibm.crypto/domains/${module_id}.${domain_id}:DELETE

Revoke the binding of a client certificate from a target domain.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X DELETE https://${dst_server_ip}/api/com.ibm.crypto/domains/${module_id}.${domain_id} -d@client.json -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

Supported request types and response formats

Supported request types:

  • DELETE

Supported response formats:

  • JSON

Example

Step 1. Get the client certificate ready in the client.json file

[
  {
    "client_pem": "<client's certificate for connection with c16server in Base64>"
  }
]

Step 2. Submit request

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/domains/${module_id}.${domain_id} -X DELETE -d@client.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

{
  "kind": "response",
  "parameters": {
     "${module_id_1}.${domain_id_1}(CONTROL)":
    {}
  }
}

If failed to bind:
[
  {
    'message': This client is not binded with target module_id.domain.id : <module_id>.<domain_id>.'
  }
]

/api/com.ibm.crypto/domains/:PUT

Refresh domains to keep consistent with that returned by lszcrypt - latest HSM cards.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X PUT https://${dst_server_ip}/api/com.ibm.crypto/domains/ -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Submit request

curl -k -X PUT https://${dst_server_ip}/api/com.ibm.crypto/domains/ -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

Returned response

{
  "kind": "response",
  "parameters": [
    "${module_id_1}.${domain_id_1}":
    {
        "client1_fingerprint":
        {
            "x509_pem_cert": "<base64 of client1 pem>",
            "x509_common_name": "common name of client1 server"
        }
    },
    "${module_id_new}.${domain_id_new}":
    {
    }
  ]
}

/api/com.ibm.crypto/camonitor:POST

Set up secure settings for CA monitor.

The endpoint accepts request in JSON and returns a response in JSON.

Synopsis of the request URL:

curl -k -X POST -d@camon.json https://${dst_server_ip}/api/com.ibm.crypto/camonitor/ -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

Supported request types and response formats

Supported request types:

  • POST

Supported response formats:

  • JSON

Example

Step 1. Define the related parameters in a file named camon.json.

[
  {
    "kind":"request",
    "parameters":{
        "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>"
    }
  }
]

Step 2. Submit request

curl -k -X POST -d@camon.json https://${dst_server_ip}/api/com.ibm.crypto/camonitor/ -H 'zACI-API: com.ibm.zaci.system/1.0' -H 'Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0' -H 'Accept: application/vnd.ibm.zaci.payload+json' -H "Authorization: Bearer ${auth_token}"

Returned response

[
  'msg': <success/error message to config secure settings for CA monitor>
]

/api/com.ibm.crypto/apilog:GET

Get detail inner system service logs, especially for logs during Rsyslog configuration process.

The endpoint accepts request in JSON and returns a response in JSON. You can modify the apilog endpoint with the following parameters:

  • service_name

    Specify which system service log is needed, support to get log of [rsyslog | c16server] system service.

  • logline_number

    Specify how many log lines are needed, support [10 - 100].

  • from_timestamp

    Specify timestamp, to get logs after that time. If you want to get the latest log lines, let it empty.

The following example shows how to specify these parameters:

{
    "kind":"request",
    "parameters":{
        "service_name": "", 
        "logline_number": "",
        "from_timestamp": ""
    }
}

Synopsis of the request URL:

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/apilog -X GET -d@apilog.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Supported request types and response formats

Supported request types:

  • GET

Supported response formats:

  • JSON

Example

The following example shows how to define the apilog parameters and the response that is returned.

Step 1. Define the apilog parameters in a file named apilog.json.

{
    "kind":"request",
    "parameters":{
        "service_name": "rsyslog",
        "logline_number": "40",
        "from_timestamp": "2023-11-02"
    }
}

Step 2. Submit the request.

curl -k -H 'Authorization: Bearer <token>' https://<crypto_appliance_host>/api/com.ibm.crypto/apilog -X GET -d@apilog.json -H "Content-Type: application/vnd.ibm.zaci.payload+json;version=1.0" -H "zACI-API:com.ibm.zaci.system/1.0" -H "Accept: application/vnd.ibm.zaci.payload+json;version=1.0"

Returned response

{
  "kind": "response",
  "parameters": {
    "server_logs": "-- Logs begin at Wed 2024-01-17 06:37:49 UTC, end at Wed 2024-01-17 08:42:15 UTC. --\nJan 17 06:37:49 5d766e598ce6 systemd[1]: Starting System Logging Service...\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: module 'imklog' already in this config, cannot be added  [v8.2001.0 try https://www.rsyslog.com/e/2221 ]\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: rsyslogd's groupid changed to 111\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: rsyslogd's userid changed to 105\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: [origin software=\"rsyslogd\" swVersion=\"8.2001.0\" x-pid=\"18939\" x-info=\"https://www.rsyslog.com\"] start\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: imjournal: No statefile exists, /var/log/rsyslog/journal_state will be created (ignore if this is first run): No such file or directory [v8.2001.0 try https://www.rsyslog.com/e/2040 ]\nJan 17 06:37:49 5d766e598ce6 systemd[1]: Started System Logging Service.\nJan 17 06:37:49 5d766e598ce6 rsyslogd[18939]: imjournal: journal files changed, reloading...  [v8.2001.0 try https://www.rsyslog.com/e/0 ]\n"
  }
}