General API Information

Integrating CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. services within your server application, such as an exchange, a custodian service, or any other application managing crypto assets, is accomplished with the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API.

This reference includes operations for completing the full CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. life cycle, including:

1. Creating accounts
2. Adding participants to an account
3. Creating vaults
4. Depositing money into vaults
5. Withdrawing money from vaults
6. Managing keychains

See the Unbound CASP User Guide for details about installing CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions..

REST API Requests

The API prefix for all CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. endpoints is:

https://<casp-server>/<comp>/api/v1.0/

The value for <comp> is the name of the coin type, such as btc, or casp.

Error Handling

Responses are formatted in the standard RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. format, with a status field showing an error code and an error field with a text description of the error. The possible error codes are described with each API.

For example, here is an apikeys request:

https://<casp-server>/casp/api/v1.0/mng/auth/apikeys

The error that is received is shown on the right.

Date: Mon, 05 Nov 2018 07:49:10 GMT
Content-Type: application/problem+json
Content-Length: 121
{
"type":"/mng/errors/operation-failed",
"title":"Authentication failed",
"details":"Password must be changed",
"status":400
}

CASP Operators and Participants

CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. has both operators and participants.

1. Operators - manage users, participants, and vaults. They initiate operations and manage policies. Each operator has a role, as described in CASP Roles.
2. Participants - members of quorumOne or more groups, comprised of participants groups that can approve or decline operations. See Participant Flows for the actions that participants are involved in.

CASP Roles

Each operator in CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. has an associated role. This role defines which actions are permissible for the operator to execute and what data the operator has access to.

Roles can be one of the following:

• Security Officer - has permissions associated with system management, such as:
  • User management - create new operator and reset operator passwords.
  • Account management - create and edit accounts.
  • ParticipantA member of any of the quorum groups. management - create and edit participants, generate activation codes.
  • Create backups.
• Trader - has permissions associated with vaults and transactions, such as:
  • Operations - start the signing process, and approve transactions.
  • Keychain management - create an address, derive a key.
    

    Note
    The Trader cannot create new operator or participants.

• Super User - has all permissions.

Warning
Use extra caution with the Super User role, since it has all available permissions.

Public Key Encoding

Some CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. operations, such as List chain addresses, provide a key encoding parameter that determines the key format. The public key encoding can be one of the following:

• DERBinary file, serialized ASN.1 structure - – ASN.1 encoded (for ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. or EdDSAEdwards-curve Digital Signature Algorithm)

• compressed – provides the x coordinates and the sign of the y coordinate (ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. only).

• uncompressed – provides the x,y coordinates of the point on the curve (ECDSAElliptic Curve Digital Signature Algorithm - A variant of the Digital Signature Algorithm (DSA) which uses elliptic curve cryptography. only).

• plain - provides the x,y coordinates of the point on the curve (EdDSAEdwards-curve Digital Signature Algorithm only).

Proof of Ownership

Proof of ownership can be achieved by verifying a signature returned by a CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. sign operation. This action proves to someone else that you hold the private key associated with the vault.

The proof of ownership process is as follows:

1. Produce a hash for signature from any plaintext using bitcoin magicHash function.

2. Create a CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. sign request with the getSignOperation endpoint to sign the produced hash.

3. From the response data received from CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions., extract the signature and recovery code.

4. Send the signature, original plaintext message, recovery code, and address to the verification entity.

5. The verification entity can verify the address and signature using the recovery code.

6. The verification entity should run the bitcoin verify message algorithm.

For a sample of the verification process, see Proof of Ownership in GitHub.

BIP32 vs BIP44

There are 2 sets of APIs for the 2 types of vault key hierarchies:

1. BIP44 vault hierarchy - With this vault hierarchy it is possible to use APIs, such as coins, accounts , and addresses. The hardened/non-hardened derivation technique that is selected is specified by the BIP44 standard, e.g., account keys always use hardened derivation and address keys always use non-hardened derivation.

2. BIP32 vault hierarchy - This vault hierarchy provides an API to create custom derivation paths with any type/hierarchy that is desired, assuming it follows the basic rule that hard derivation cannot be performed on keys that derived via non-hard derivation.

Accounts

Click here to open the Account APIs.

An account is a container for a set of vaults and participants that manage these vaults. An account may represent a client of the system, a trader, an organization, etc. The CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. service supports creating different accounts, managing account participants (human users or machine BOT's), creating secure vaults for the account, and executing different crypto assetDigital information that needs to be securely stored. transactions within the account.

The CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. service supports the notion of global accounts, which can manage vaults across other accounts. This notion can support the use case of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. service providers managing vaults on behalf of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. clients.

Attributes

Attribute templates enable you to add custom static attributes to a CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. vault during vault creation. Attributes consist of one or more of the following types: string, numeric, date and Boolean. To ensure security, the attributes are approved by the admin group during vault creation. A customerThe entity that initially holds the crypto asset and requests storage in the crypto asset vault. can use these attributes to add logic to a policy. For example, a transaction that is initiated during a predefined date range will go through a certain MofNDefines how many participants of a group are required for an approval. M out of N participants are sufficient to reach the quorum. approval policy.

Audit Reports

Click here to open the Audit Report APIs.

Audit reports can be generated detailing account, user, vault, and sign operations. There is also the capability to delete old data.

These reports are tamper-proof, using a scheme where each line is signed. An endpoint is provided to verify the integrity of the audit report.

A script is also provided with the installation that resets the audit data. If needed, run the script with this command:

sudo casp_delete_ukc_secrets

Authentication

Click here to open the AuthenticationProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. APIs.

Most endpoints require authentication to submit a request to the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. server. The API reference for each endpoint specifies the types of authentication needed to access the endpoint.

Endpoints in the Getting Started section do not need authentication. This allows you to easily retrieve the system status.

CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. uses username/password and API keys to add a layer of security to the API requests from users (see CASP Users and Participants for a definition of users).

Username and Password

For short term access, such as for the web UI, the user can use a username and password to generate an access token that is valid for 20 minutes by calling the Get access and refresh token endpoint. The access token must be added to the authorization header (as a bearer token) to every RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. call.

To get or refresh the access token, call the Get access and refresh token endpoint. The following code samples show the types of authentication that can be used with this endpoint.

1. Using a username/password in an AuthenticationProcess used to achieve sufficient confidence in the binding between the Entity and the presented Identity. header.

curl --request POST \
 --url http://localhost:8888/casp/api/v1.0/mng/auth/token \
 --header 'authorization: Basic c286Y2FzcCBydWxleno=' \
 --header 'content-type: application/json' \
 --data '{
          "grant_type":"password"
 }'

2. Using username/password in the body.

curl --request POST \
 --url http://localhost:8888/casp/api/v1.0/mng/auth/token \
 --header 'content-type: application/json' \
 --data '{
          "grant_type":"password",
          "client_id":"so",
          "password":"password"
 }'

Refresh the Token

Once you have an access token, you can use the same endpoint to refresh the token.

This is an example of refreshing the token:

curl --request POST \
 --url http://localhost:8888/casp/api/v1.0/mng/auth/token \
 --header 'content-type: application/json' \
 --data '{
          "grant_type":"refresh_token",
          "refreshtoken":"c386ZjU4NGE1ZjUtNjRlOS00M1M9LWIyOTItOWYzZjc0NjUxODg6"
 }'

API Key

For applications or scripts that require long term access, an API key with a one-year time limit can be created. The CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. Admin first creates an access token and then uses it to generate an API key by calling the POST /auth/apikeys operation (and providing the credentials). The returned API key must be added to the authorization header (as a bearer token) for every RESTRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. call. The Admin can generate several API keys for different app usages.

Token Usage

Once you have an access token or API key, you can call endpoints using it, such as:

curl --request GET \
--url http://localhost:8888/casp/api/v1.0/mng/auth/users \
--header 'authorization: Bearer dXNlcjExMTE6NWRmYWQwN2EtODgyMi00NzM0LTg4NTMtYjA4YjhkNTc0ZTYx'

The header field has the format:

--header 'authorization: Bearer <token/key>'

The <token/key> field can be the access token or the API key.

Backup

Click here to open the Backup APIs.

CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. supports backing up key material and restoring the backup information for the different levels of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. entities: per vault, per sub-account (for HDHierarchical Deterministic - a type of deterministic Bitcoin wallet derived from a known seed, that allows for the creation of child keys from the parent key. Because the child key is generated from a known seed there is a relationship between the child and parent keys that is invisible to anyone without that seed. wallets), and per specific address (for HDHierarchical Deterministic - a type of deterministic Bitcoin wallet derived from a known seed, that allows for the creation of child keys from the parent key. Because the child key is generated from a known seed there is a relationship between the child and parent keys that is invisible to anyone without that seed. wallets).

When backing up a key, the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. backup mechanism supports a publicly verifiable backup. Using only the backup public key, you can verify that the encrypted data is indeed the EC private key, which matches the known EC public key.

Three APIs are provided for backups:

• Backup a single key in a deterministicCalculation that each time results in the same value (Non-hierarchical) vault: Get vault backup data
• Backup a sub-account key in an HDHierarchical Deterministic - a type of deterministic Bitcoin wallet derived from a known seed, that allows for the creation of child keys from the parent key. Because the child key is generated from a known seed there is a relationship between the child and parent keys that is invisible to anyone without that seed. (BIP44) vault: Get backup for account
• Backup a specific key in an HDHierarchical Deterministic - a type of deterministic Bitcoin wallet derived from a known seed, that allows for the creation of child keys from the parent key. Because the child key is generated from a known seed there is a relationship between the child and parent keys that is invisible to anyone without that seed. (BIP32) vault: Get public key backup data

General Status

Click here to open the General Status APIs.

General endpoints are provided to check the health of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. service, the supported ledgers, etc.

Identity Providers

CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. can leverage CORE integration with the OpenID Connect (OIDCOpenID Connect is identity layer on top of the OAuth 2.0 protocol) providers enabling the Single Sign-On (SSOSingle Sign-On) authentication for the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. partition users. The CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. UI login page presents the standard login option and a list of the registered SSOSingle Sign-On providers. To log in, specify the required partition, select the personal authentication option, and proceed as directed.

Keychain Management

To open the Keychain Management APIs, click for Built-in Wallets or BYOW.

Some implementations require a higher level of anonymity, meaning that a key is used a minimal number of times before switching to a new key. To accomplish this goal, CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. provides keychains, known as hierarchical deterministic wallets (or "HDHierarchical Deterministic - a type of deterministic Bitcoin wallet derived from a known seed, that allows for the creation of child keys from the parent key. Because the child key is generated from a known seed there is a relationship between the child and parent keys that is invisible to anyone without that seed. Wallets"). These keychains enable the creation of many keys for a single vault.

Working with the currency layer, CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. supports a specific hierarchy structure as defined in the BIP44 scheme. This scheme supports the following:

• Generating any number of sub-accounts within the same vault. You can use this approach for creating segregated accounts within the same vault.
• Generating many addresses for each sub-account.

Operators

Click here to open the Operator APIs.

Operators manage users, participants, and vaults. They initiate operations and manage policies. An operator can be configured to have 2-factor authentication ("2FATwo-factor authentication - Authentication method that requires both something a user has (for example, a certificate) and something the user knows (for example, a password)"). If enabled, when the operator attempts to log into the web interface, an authentication request is sent to that user's mobile device. The user is only permitted to access the web interface after 2FATwo-factor authentication - Authentication method that requires both something a user has (for example, a certificate) and something the user knows (for example, a password) approval on the mobile device.

Participants

Click here to open the ParticipantA member of any of the quorum groups. APIs.

A participantA member of any of the quorum groups. can be a human within the account or a BOT taking part in crypto assetDigital information that needs to be securely stored. transactions. Each participantA member of any of the quorum groups. owns a share of the cryptographic material that is part of the different transactions. CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. supports participants using any relevant platform, including mobile devices, laptops, and different server platforms for BOT's.

Policy Management

To open the Policy Management APIs, click for Built-in Wallets or BYOW.

Each CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. vault has a set of risk-based quorumOne or more groups, comprised of participants policies associated with it, which are defined during vault creation (see Risk-Based Policy Vaults for policy configuration in the Web UI). These policies assign a different quorumOne or more groups, comprised of participants policy to different transactions, based on the transaction details (such as the transaction amount or the time of day).

MofN Quorum Groups

Approvals are defined by a group of authorizing entities, of which a minimal-size subset (called a quorumOne or more groups, comprised of participants) is required to approve the transaction. M approvals from a set of N entities is known as "MofNDefines how many participants of a group are required for an approval. M out of N participants are sufficient to reach the quorum.". For example, the client may define 8 entities, of which 4 must approve the transaction. Another example is where there must be 3 approvals from group A and 2 approvals from group B.

The number of groups, size of groups, and the size of the approving subset is fully flexible and can be different for each vault.

Policy Architecture

The following figure shows the architecture of the policy management components.

There are two types of quorumOne or more groups, comprised of participants groups:

1. Admin Groups - quorumOne or more groups, comprised of participants groups used to approve vault creation and subsequent policy updates.
2. Approval Groups - quorumOne or more groups, comprised of participants groups used to approve operations.

The Security Officer (see CASP Roles) of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. system can create, read, update, and delete (CRUDSet of Create, Read, Update and Delete operations.) policies in a vault. These actions (except for read) require the approval of the admin groups defined for the vault.

Each policy is comprised of a set of policy rules and a set of approval groups. The policy rules define limits on the transaction amounts and restrictions on the time of day when the policy is active. You can create as many policies as required for your vault.

When a transaction, such as a withdrawal, is requested, CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. checks the list of policies to determine the first policy that has rules that match the conditions of the transaction. This policy is then applied to the policy resulting in a request to the approval groups associated with the policy.

Incoming Transaction Approval

In regulated organizations, it is not only important to verify withdrawals (by signing a transaction), but also to verify the legitimacy of deposits, such as to protect against money laundering. Verifying deposits involves taking a transaction that already occurred (i.e., it is already on the blockchain) and checking that it aligns with the organization's policy.

CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. incoming transaction vaults include all mechanisms available to a vault for withdrawals, such as data collectors, policies, and signing quorums. The result is not a signed transaction that is sent to the ledger, but rather a signature on an existing transaction that denotes that the transaction is legitimate and its value can be included in the vault balance.

The feature is implemented by assigning an incoming transaction vault to the main vault. The main vault then either evaluates and signs the transaction using the properties of the incoming transaction vault or its own properties.

To create an incoming transaction vault:

1. Create a new vault and set these parameters:

   • incomingTransactionVault - set to "true" to declare the vault as an incoming transaction vault.

   • incomingTransactionVaultId - give the vault an ID that is used to reference it in signing requests.

2. Add any other relevant properties, such as the policy to that vault.

3. Create the main vault, using the additional parameters incomingTransactionVaultId, with the corresponding ID value of the incoming transaction vault, and incomingTransactionVault set to false.

4. When you want to use the incoming transaction vault, use the alternate signing endpoint called Start incoming transaction signing. This endpoint signs using the vault key from the incoming transaction vault.

Whitelisting

Vaults can be created with a policy that contains rules that only apply for a whitelist or derived whitelist.

• A whitelist is a list of destination addresses for which the rule applies.
• A derived whitelist can whitelist all keys that can be derived from a specific key. The destination addresses must be able to be derived from the public key corresponding to the provided key.

The whitelist is specified in the endpoint for creating a new vault.

For example, the following is part of a request showing both a whitelist and derived whitelist:

"whiteList":
  [
    "F367002FFA7e97FFE5dd13855Ab5341Be18BC0fF"
  ],
"derivedWhiteList":
  [
    {
      "chainCode": "6559FE7E680D021D715101D5B05193A5D0BDD11B55D9B949116EA0FD17268343",
      "publicKey": "3056301006072A8648CE3 ... E5CB1D1FAE95522A912F0E1E7CFB9CF",
      "level": 1,
      "parentFingerprint": "1811729397",
      "childNumber": 12
    }
  ],

When sending a sign request for this vault, there is a parameter called derivedWhitelistChildNumbers that specifies the child number. This parameter is needed when there are more than 1000 keys. For example: "derivedWhitelistChildNumbers": [ 50008 ]

It is important to note the following about derived whitelists:

1. Each derivedWhiteList item represents the parent.

2. The sign request parameter derivedWhitelistChildNumbers specifies the child number.

3. If derivedWhitelistChildNumbers is not specified, the first 1000 keys from the parent are derived (starting with childNumber 0 and ending with childNumber 999).

4. CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. checks that all the destination addresses in the transaction are either in the first 1000 derived children or they are change addresses.

For example, if we want to send money to key m/42'/0'/2'/0/15, we specify in the derivedWhiteList the BIP details of the parent key: m/42'/0'/2'/0. Furthermore, all keys from key m/42'/0'/2'/0/0 to key m/42'/0'/2'/0/999 would be accepted by this rule.

Reports

Click here to open the Report APIs.

These endpoints provide reports about various aspects of the CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. system, such as vault details, user, details, and account details.

Trusted Systems

Trusted systems enable the exchange of data between separate CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. systems (i.e. systems that have an air gap) and enforce approval of transactions in these different systems. For example, they can be used to create a hot/cold environment where vault generation (and the key ceremony) occurs in the cold CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. system. Transactions are signed first by participants in the cold system and then by participants in the hot system.

Vault Operations

To open the Vault Operation APIs, click for Built-in Wallets or BYOW

A vault is a secure container for the cryptographic material used to protect a crypto assetDigital information that needs to be securely stored., such as the seed or private key. CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. uses Multiparty Computation (MPCMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private.) to split the crypto material between the different participants in the vault, which ensures that the material never exists in a single place. In addition, only the approved set of participants can complete a transaction based on the vault definition.

A QuorumOne or more groups, comprised of participants vault shares the responsibility of executing a transaction between many different participants in a structure defined by the vault policyA set of conditions that define the MofN groups used for quorum-based transactions.. The vault policyA set of conditions that define the MofN groups used for quorum-based transactions. contains a quorumOne or more groups, comprised of participants-based structure where there are any number of groups, any threshold value per group, any tree structure between different groups, etc. The MPCMultiparty computation - A methodology for parties to jointly compute a function of their inputs while keeping those inputs private. protocols used by CASPUnbound’s Crypto Asset Security Platform (“CASP”) provides the advanced technology and the architecture to secure crypto asset transactions. ensure that if and only if the quorumOne or more groups, comprised of participants definition is satisfied, a transaction can take place, which is enforced on the cryptographic level.

Use the relevant endpoint based on BYOWBring Your Own Wallet - support any coin or crypto asset type using the CASP APIs to control the vault and key operations. or the currency you want to work with. The list of supported currencies and the matching short names can be found in Supported Wallets. In this document, Bitcoin is used as an example.

The main endpoints for vault management are:

/btctest/api/v1.0/accounts/{accountId}/vaults

and

/btctest/api/v1.0/vaults/{vaultId}