Fetch Approval Tasks

This page describes how authorization apps can fetch the list of pending approval tasks.

Recall that as part of its workflow engine, the TSB automatically generates "approval tasks" for pending SKA key operations. Every approver can poll the TSB and receive their list of pending tasks. When a task is available, the app shows the tasks to the human approver and asks them to approve or reject the request.

Apps can get the list of pending tasks by calling the /v1/filteredAllApprovalTask endpoint. There are also endpoints for querying specific types of pending tasks, such as sign/unwrap/etc.

API Authentication

Recall that the main API authentication methods are JWT, mTLS, and API keys. These methods are intended for service-to-service authentication, that is, between the TSB and your business applications.

How does API authentication work for mobile authorization apps accessing the TSB? The challenge is that 1) multiple app installations should not share credentials (which would be the case when hardcoding API keys) and 2) every approver should only have access to their own approval tasks.

The solution is to let authorization apps sign the current timestamp. Through this signature, the approver proves that they recently controlled the approver private key, and hence that they are authorized to query the pending tasks for this approver.

Authorization apps should do the following:

1. Get the current timestamp in ISO-8601 format.
2. Sign the timestamp with the approver private key.
3. Base64-encode the signature.
4. Include the timestamp and timestampSignature values in the request body when calling one of the affected endpoints (listed below).

TIMESTAMP=$(date -u "+%Y-%m-%dT%H:%M:%S+00:00")
SIGNATURE=$(echo -n $TIMESTAMP | openssl dgst -sha256 -sign $PRIVATE_KEY_FILE | openssl enc -base64 | tr -d '\n')

Endpoints

This timestamp-signature-based API authentication applies to all endpoints that mobile apps are expected to need. In particular:

• /v1/task
• /v1/filteredAllApprovalTask
• /v1/filteredBlockKeyApprovalTask
• /v1/filteredUnblockKeyApprovalTask
• /v1/filteredModifyKeyApprovalTask
• /v1/filteredSignApprovalTask
• /v1/filteredSelfSignCertificateApprovalTask
• /v1/filteredCsrSignApprovalTask
• /v1/filteredCertificateSigningRequestApprovalTask
• /v1/filteredCertificateApprovalTask
• /v1/filteredDecryptApprovalTask
• /v1/filteredUnwrapKeyApprovalTask

Note that the /v1/approval endpoint is not covered by this. This is because its request body already contains a signature over the approvalToBeSigned. The TSB can verify that this signature is valid and belongs to a real, pending approval task.

Onboarding a Backend Service to Poll Approval Tasks

Instead of mobile authorization apps directly accessing the TSB, you may want to have a separate backend service that polls the TSB for approval tasks and distributes these tasks to your mobile apps. For example, this is useful for implementing push notifications in your app. Your backend would handle the push registrations for all apps, and send pushes via the push service of your choice (Apple Push Notification, Firebase Cloud Messaging, etc.)

In such an architecture, this backend needs to pass the access control on the above mentioned endpoints. However, this backend is not an approver, and thus does not automatically have a public key associated with it. The solution for this is to:

1. Generate a public-private key pair for your backend.
2. Onboard the public key to the TSB.

Then, your backend can fill out the timestamp and timestampSignature fields just like a mobile application would. The difference is that because its public key is specifically allow-listed in the TSB configuration, your backend can query the tasks of all approvers. If the backend wants to filter for a specific approver, they can set the approverPublicKey or the approverCertificate field. Note that since its public key won't be listed in any SKA policy, this backend cannot approve any tasks.

The certificate for your backend service is also called the timestamp signer certificate.

tip

In this flow diagram, push is only used to wake up the Authorization App. The app then directly contacts the TSB to fetch the task. This avoids sending sensitive information in the push message.

Create a Timestamp Signer Certificate

First, create a key pair and a self-signed certificate. Configure your backend so that it is able to use the private key for signing timestamps later.

OpenSSL

openssl req -new -x509 -sha256 -newkey rsa:4096 -days 3650 -subj '/CN=TSB-Timestamp-Signer' -keyout tsb-timestamp-signer.key -out tsb-timestamp-signer.crt

This creates two files:

• tsb-timestamp-signer.crt (certificate of the public key)
• tsb-timestamp-signer.key (private key)

Primus REST API

See this tutorial for how to create a key pair and an accompanying self-signed certificate on the Primus HSM through the REST API.

Onboard the Timestamp Signing Certificate to the TSB

The timestamp signing certificate must be onboarded to the TSB, so that the TSB knows how to verify the signature. The TSB operator needs to add the certificate to the application.yml configuration file of the TSB.

CloudHSM (TSBaaS)

If you are using CloudHSM with TSBaaS, please open a support ticket and attach your timestamp signer certificate to the ticket. Securosys will onboard the certificate for you.

On-premise TSB

For locally deployed TSB instances, onboard the certificate as follows:

1. Open the application-local.yml file of your TSB deployment.
2. Find or add the general.allowedTimestampSigningCertificates field.
3. Add the certificate file path to the list of allowedTimestampSigningCertificates
4. Amend your Docker setup to mount the certificate into the container at the path you just specified.
5. Redeploy the Docker container.

For example:

general:
  allowedTimestampSigningCertificates:
    - file:/etc/app/config/tsb-timestamp-signer.crt