Create a Key

You can create new keys using the POST /v1/key endpoint. Below, you can find various example request bodies that show how to create keys of different types.

warning

Once a key has been generated, it can be hard or impossible to modify its attributes later. Which changes are possible depends on the settings that were applied during generation. For example, a normal key cannot be later upgraded to an SKA key.

Generally, you should design your applications so that they can roll over to a different key. This allows you to simply generate a new key with the correct attributes, rather than trying to edit the old key.

Create a Blockchain Wallet Master Key

For crypto currency wallets, the HSM supports key derivation via SLIP-10 for EC and ED keys. For details, see the blockchain tutorials. When using key derivation, you need a master key from where the derivation starts.

When you create the master key, set the relevant key attributes: derive: true and slip10: true. This allows the later generation of child keys from such a master key. For details, see this tutorial.

Alternatively, instead of creating the master key with this endpoint, you can also import it from a seed.

RSA (Rivest-Shamir-Adleman)

{
    "label": "<keyname>",
    "password": [ "R","E","P","L","A","C","E" ],
    "algorithm": "RSA",
    "keySize": 2048,
    "attributes": {
        "sign": true,
        "extractable": false,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "decrypt": false,
        "unwrap": false
    }
}

EC (Elliptic Curve Cryptography)

    {
        "label": "<keyname>",
        "password": [ "R","E","P","L","A","C","E" ],
        "algorithm": "EC",
        "curveOid": "1.3.132.0.10",
        "attributes": {
            "encrypt": true,
            "decrypt": true,
            "verify": true,
            "sign": true,
            "wrap": true,
            "unwrap": true,
            "derive": false,
            "bip32": false,
            "slip10": false,
            "extractable": false,
            "modifiable": true,
            "destroyable": true,
            "sensitive": true,
            "copyable": false
        }
    }

ED (Edwards-Curve Digital Signature Algorithm)

    {
        "label": "<keyname>",
        "password": [ "R","E","P","L","A","C","E" ],
        "algorithm": "ED",
        "curveOid": "1.3.101.112",
        "attributes": {
            "encrypt": true,
            "decrypt": true,
            "verify": true,
            "sign": true,
            "wrap": true,
            "unwrap": true,
            "derive": false,
            "bip32": false,
            "slip10": false,
            "extractable": false,
            "modifiable": true,
            "destroyable": true,
            "sensitive": true,
            "copyable": false
        }
    }

AES (Advanced Encryption Standard)

{
    "label": "aes",
    "algorithm": "AES",
    "keySize": 256,
    "attributes": {
        "encrypt": true,
        "decrypt": true,
        "verify": true,
        "sign": true,
        "wrap": true,
        "unwrap": true,
        "derive": false,
        "bip32": false,
        "extractable": false,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "copyable": false
    }
}

Dilithium (Crystals-Dilithium, PQC)

{
    "label": "pqc_dilithium",
    "password": null,
    "algorithm": "DILITHIUM_L5",
    "attributes": {
        "sign": true,
        "extractable": false,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "decrypt": false,
        "unwrap": false
    }
}

LMS (Leighton–Micali Signatures, PQC)

{
    "label": "lms_dilithium",
    "password": null,
    "algorithm": "LMS",
    "attributes": {
        "sign": true,
        "extractable": false,
        "modifiable": true,
        "destroyable": true,
        "sensitive": true,
        "decrypt": false,
        "unwrap": false
    }
}

BLS (Boneh-Lynn-Shacham)

{
  "label": "bls_approver",
  "algorithm": "BLS",
  "attributes": {
    "encrypt": true,
    "decrypt": true,
    "verify": true,
    "sign": true,
    "wrap": true,
    "unwrap": true,
    "derive": false,
    "bip32": false,
    "slip10": false,
    "extractable": true,
    "modifiable": true,
    "destroyable": true,
    "sensitive": false,
    "copyable": false
  },
  "policy": null
}

HMAC

{
    "label": "hmacsha256",
    "password": null,
    "algorithm": "HMACSHA256",
    "attributes": {
        "sign": false,
        "extractable": false,
        "modifiable": false,
        "destroyable": false,
        "sensitive": true,
        "decrypt": false,
        "unwrap": false
    }
}