Skip to main content

Create an SKA Key

This tutorial explains how to create an SKA key through the TSB's REST API.

Prerequisites​

When you create an cryptographic key on Primus HSM, you can decide whether to:

  • Not specify any SKA policy. In this case, the key will be a normal key. Warning: A normal key cannot be later upgraded to an SKA key!
  • Specify an empty SKA policy. This creates an SKA key with a policy that is always fulfillable. This allows you to later add approvers to the policy, thus restricting access to the SKA key.
  • Specify approvers in the SKA policy. This restricts the SKA key from the very beginning. This requires that you have already created approvers, since you need to specify their public keys or their certificates in the SKA policy.

Create​

Rules

This example demonstrates how to create an RSA key with a policy enabled. It is simplified with a quorum of 1 and a single approver on rule-use. You can expand the policy section with rule-modify, rule-block, rule-unblock. For more information about SKA Policies, see the SKA documentation.


The ruleUse means that whenever the key is used for cryptographic operations, such as signing, decrypting, unwrapping, or issuing certificates, the request must be authorized by the designated approver in the policy.


Demo Helper

To locally generate an approver key pair with OpenSSL, you can use this helper script.

Run it with sh create_rsa.sh approverName

POST /v1/key

{
    "label": "TSB_TUTORIAL_1-RSA",       # Label must be unique and is used for any request of the key action
    "algorithm": "RSA",
    "keySize": 2048,                    # keySize is required for RSA
    "attributes": {                      # For this example, we'll assume the key will be used only for signing. We also rely on defaults for most attributes (see in response)
        "decrypt": false,
        "sign": true,
        "unwrap": false,
        "destroyable": true 
    },
    "policy": {                          # To better understand structure of the policies, refer to the concept diagram
        "ruleUse": {                     # We'll set a very simple policy - 1/1 approval with no timelock and a 10 minute timeout
            "tokens": [
                {
                    "name": "Token1",
                    "timelock": 0,
                    "timeout": 3600,     # Time restrictions are defined in seconds and must be multiples of 60
                    "groups": [
                        {
                            "name": "Group1",
                            "quorum": 1,  # Quorum of 1 means that only 1 approver needs to sign in order to get a request EXECUTED
                            "approvals": [
                                {
                                    "type": "certificate",   # the type can vary based on your preference: certificate, public-key or onboarded_approver_certificate
                                    "value": "MIIDAjCCAeoCCQCcSLgNCjDsRzANBgkqhkiG9w0BAQsFADBDMQswCQYDVQQGEwJDSDEPMA0GA1UECAwGWnVyaWNoMQ8wDQYDVQQHDAZadXJpY2gxEjAQBgNVBAoMCVNlY3Vyb3N5czAeFw0yMDA1MTExNDI5MDdaFw0yMTA1MTExNDI5MDdaMEMxCzAJBgNVBAYTAkNIMQ8wDQYDVQQIDAZadXJpY2gxDzANBgNVBAcMBlp1cmljaDESMBAGA1UECgwJU2VjdXJvc3lzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArA0bxSqhL7xfvcHbKKa8wMTMsIeJfYRdIgPxp5cU9JcmV86kyfpyRcSNSi44LVeNmAi94F3OZrXXi6CZvWrFL+VcewUtUSu+kG5oLJ9T4O6R2I5GO2Ev1HJnK3WfHOsFKFxLGzmKyjEkSLGgopY+Nh74K8Q6yxsvQPETOs9TzQiUXFYlfEZnbjUWG4eAgW9WWEopmK/X295ToOuTHFzmzO00btkjAy6vwWOabCE4kaJg+bCNW1snZz84uonr60rB9H0Mj98RbTfbDyMh6cIkaj8WrXeaYh4fxQYXApYu3nzhe3Q1bNCzV5M68rCsgVrmWcK/xUhM9BK6QHSwS/l76wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQBNmg+gx2mH+fkU/dtM+tDvMIj2SY4pNU8H144aRY9I5kARN7Uwp+zRfJC+rCxrrYxXmx/OD+mIrTAHxPd5WuUWgULB6DXPho5Tyl4Czt6qOuzl7Qp7n1G9R/evZCPyEHflcGVEko/uCL5N8Ch9YboW5QwTrdftnL+zLLC5nON7KUCqbtVrDSdeMKF+dHKTX4Z90gdbv1C8x1fMWrsaoNw194DNBZCTVe4Di69xz3lHNEWVZ460mqKg0n5010VfEQqA92ceNJhjl4hgNMH9+asdBVAWmt0gk4PJUbqtuOKGKyxqi2k9QX8N2tjlsuMJmwRIw2YsZN4EKqQZ+0NAn1N7"
                                                            # Certificate or PublicKey values must be provided without new lines
                                }
                            ]
                        }
                    ]
                }
            ]
        },
    "keyStatus": {                     # Make sure this is inside of policy object
        "blocked": false               # If setting this to true, make sure ruleUnblock is defined
    }
    }
}
Key Parameters
ParameterDescription
labelThe keyname e.g., TSB_TUTORIAL_1-RSA.
algorithmThe key algorithm. Supported algorithms.
keySizeThe size of key. Supported sizes
curveOidThe curveOid (for EC/ED only). Supported curve OIDs
Policy Parameters
ParameterDescription
ruleUseThe ruleUse for private-key Operations such as: v1/sign, /v1/decrypt, /v1/unwrap
ruleModifyThe ruleModify to modify the policy: v1/modify
ruleBlockThe ruleBlock to block usage of the private-key: v1/block
ruleUnblockThe ruleUnblock to unblock a blocked key: v1/unblock
tokensA Token array, which are OR associated, if multiple tokens are specified, either token1 or token2 has the be satisfied.
timelockThe timelock before the approval is accepted, in seconds, a multiple of 60
timeoutThe timeout after which no approvals are accepted, in seconds, a multiple of 60
groupsAn Group array, which are AND associated, if multiple groups with quorum 1 is specified, each group has to fullfill the quorum.
quorumQuorum of 1 means that only 1 approver needs to sign in order to get a request EXECUTED
approvalsThe approvers (mobile applications) onboarded to the policy. In order to use the key, the Approver has to approve the request, before it gets executed.
typeThe type can vary based on your preference: certificate, public-key or onboarded_approver_certificate (for approverManagement API only!)
typeThe type, for the use of Securosys Authorization App, it is always onboarded_approver_certificate
valueThe name of the onboarded approver.
Policy

For more information, see the SKA documentation.

For the attributes, see the Key Attributes documentation.

What's next?​

Get started withCloudHSM for free.
Other questions?Ask Sales.
Last updated on
Feedback
Need help?