Concept: Effective Capabilities

Effective Capabilities (Tying It All Together)

This document describes how Object-related concepts interact with each another.

Let us assume that we are establishing a Session with Authentication Key 0xabcd so that the Session can use the Asymmetric Key 0x1234 to sign some data. We are assuming that Asymmetric Key 0x1234 is an RSA 2048-bit key and that we would like to generate a signature using RSASSA-PSS.

Create and Authenticate a Session

Creating and authenticating a Session requires knowledge of what the long-lived keys are (or what the associated derivation password is).

When a valid Session is established, certain properties of the Authentication Key used to create the Session are inherited by the Session itself. These are:

  • The Domain(s) to which the Authentication Key belongs (for more information, see Concept: Domain),
  • The Capabilities of the Authentication Key (see Concept: Capability) and
  • The Delegated Capabilities (see Concept: Capability) associated with Authentication Key 0xabcd .

The Session’s inherited properties serve to ensure that the only Objects stored in the HSM 2 that we can see and access are those that belong to the same Domain(s) as Authentication Key 0xabcd.

Generate a Signature

The required capability must be set on both the Authentication Key used to establish the Session (Authentication Key 0xabcd) and the target Object used to perform the operation (Asymmetric Key 0x1234).

Assuming that Asymmetric Key 0x1234 is in one such Domain, we can now continue and ask the HSM 2 to generate a signature. To do so we will send the Sign Data command over the Session. It will not execute successfully unless the arguments of the command are valid, i.e., no malformed data can be sent to the device or an error will occur.

Both Authentication Key 0xabcd and Asymmetric Key 0x1234 must have the Capability sign-pss set.

Effective Capabilities and Role Definition

The overlap between

  • The Capabilities of the Authentication Key used to establish the Session and
  • The Capabilities of the target Object involved in the operation

defines the Effective Capabilities. An operation on a given target Object over a given Session can succeed only if the Capabilities required by the operation are included in the Effective Capabilities.

The interaction between Domains and Effective Capabilities enables flexible setup and role definition. For example,

  • It is possible to assign a set of Capabilities to an Object, and then distribute those Capabilities across different Authentication Keys so that each key is enabled to perform only a single operation on the target Object, and no key performs the same operation as any other key.
  • Similarly, it is possible to disable specified operations by not assigning the requisite Capabilities to an Authentication Key. For example, an “Administrator” Authentication Key could be enabled only to create keys while a “User” Authentication Key could be enabled only to use those same keys.

Workflow

  1. Determine which Objects will have operations performed on them

  2. Determine which Authentication Keys you will use

  3. Determine which operations will be performed

  4. Use a spreadsheet (if necessary) to map out the interaction between the first three items

  5. With the aid of the spreadsheet, create domains to enable the interaction.

    Note

    Authentication Keys are Objects and thus can belong to multiple Domains.

  6. You could construct your domains:

    • per operation - put an Object and an Authentication Key into each domain, or
    • per Object - put the Authentication Key(s) for all the operations to be performed on each Object into a single domain
    • per Authentication Key - put the requisite Object(s) into each Domain.

    For example, if you wanted Jan to do the signing and Ola to do the importing, you could adopt any of the above options, but the Effective Capabilities enable you to assign far more complex webs of responsibilities.

  7. Use the spreadsheet to set the Capabilities and Delegated Capabilities appropriately, “appropriateness” being determined by the Objects and operations to be performed on them.