Key Access Object

Summary

A Key Access Object stores not only a wrapped (encrypted) key used to encrypt the file's payload, but also additional metadata about how it is stored.

Example"

{
  "type": "wrapped",
  "url": "https:\/\/kas.example.com:5000",
  "kid": "6f3b6a82-2f30-4c8a-aef3-57c65b8e7387",
  "sid": "split-id-1",
  "protocol": "kas",
  "wrappedKey": "OqnOETpwyGE3PVpUpwwWZoJTNW24UMhnXIif0mSnqLVCUPKAAhrjeue11uAXWpb9sD7ZDsmrc9ylmnSKP9vWel8ST68tv6PeVO+CPYUND7cqG2NhUHCLv5Ouys3Klurykvy8\/O3cCLDYl6RDISosxFKqnd7LYD7VnxsYqUns4AW5\/odXJrwIhNO3szZV0JgoBXs+U9bul4tSGNxmYuPOj0RE0HEX5yF5lWlt2vHNCqPlmSBV6+jePf7tOBBsqDq35GxCSHhFZhqCgA3MvnBLmKzVPArtJ1lqg3WUdnWV+o6BUzhDpOIyXzeKn4cK2mCxOXGMP2ck2C1a0sECyB82uw==",
  "policyBinding": {
    "alg": "HS256",
    "hash": "BzmgoIxZzMmIF42qzbdD4Rw30GtdaRSQL2Xlfms1OPs="
  },
  "encryptedMetadata": "ZoJTNW24UMhnXIif0mSnqLVCU=",
}

keyAccess

Parameter	Type	Description	Required?
`keyAccess`	Object	KeyAccess object stores all information about how an object key OR key split is stored, and if / how it has been encrypted (e.g., with KEK or pub wrapping key).	Yes
`type`	String	Specifies how the key is stored.Possible Values: remote The wrapped key (see below) is stored using Virtru infrastructure and is thus not part of the final TDF manifest. wrapped Default for TDF 3.x and newer, the wrapped key is stored as part of the manifest. remoteWrapped Allows management of customer hosted keys, such as with a Customer Key Server. This feature is available as an upgrade path.	Yes
`url`	String	A url pointing to the desired KAS deployment	Yes
`kid`	String	Identifier for the KAS public key, such as its thumbprint. The current preferred identifier can be looked up using the `kas_public_key` endpoint. For compatibility, our reference implementation uses the associated x509 certificate's fingerprint, although this may be a UUID or other simple string selector.	Yes
`sid`	String	A key split (or share) identifier. To allow sharing a key across several access domains, the KAO supports a 'Split Identifier'. To reconstruct such a key, use the `xor` operation to combine one of each separate sid, at least under the current encryption information type (`split`).	Optional
`wrappedKey`	String	The symmetric key used to encrypt the payload. It has been encrypted using the public key of the KAS, then base64 encoded.	Yes
`policyBinding`	Object	An object that contains a keyed hash that will provide cryptographic integrity on the policy object, such that it cannot be modified or copied to another TDF, without invalidating the binding. Specifically, you would have to have access to the key in order to overwrite the policy.	Yes
`encryptedMetadata`	String	Metadata associated with the TDF, and the request. The contents of the metadata are freeform, and are used to pass information from the client, and any plugins that may be in use by the KAS. The metadata stored here should not be used for primary access decisions. Note: `encryptedMetadata` is stored as a base64-encoded string. One example of the metadata, decoded and decrypted, could be, depending on specific needs:`{authHeader:"sd9f8dfkjhwkej8sdfj",connectOptions:{url:'http://localhost:4010'}}`	Yes

policyBinding

Parameter	Type	Description	Required?
`alg`	String	The algorithm used to generate the policy binding hash.	Yes
`hash`	String	A Base64 encoding of HMAC(POLICY,KEY), where: POLICY `base64(policyjson)` that is in the “encryptionInformation/policy” HMAC HMAC SHA256 (default, but can be specified in the alg field described above) KEY Whichever Key Split or Key that is available to the KAS (e.g. the underlying AES 256 key in the wrappedKey.

The encryptionInformation field allows storing not just one, but a list of KeyAccess objects. This allows the same data encryption key to be encapsulated by multiple access services, or for the key to be split using an XOR among two or more access services.

To support both functionalities together, the sid identity field indicates if a split occurs and allows for selection of the necessary components to reassmble the data encryption key.

Examples

Sample Key Content

Suppose we have encrypted our payload with a 128 bit AES data encryption key (DEK) of:

Data Encryption Key (DEK)

85 c0 b0 57 5b a0 a8 3c 04 48 b2 f4 85 96 e5 31

Keys for alpha.kas

Keys for beta.kas

Keys for local.hsm

Shared Key Access

If we want to allow access to the DEK from two different KAS, we can encapsulate the DEK twice.

- policyBinding: |
    Wm1ReFkyWm1PREk0WldaaU5qQXpOamszTUdJMk5HSXdNREkyTTJGbE1XUXdaVFl6TUdFeU9EWTJO
    RE01WVRkaE1EbGpPR0l6TUdVM01qVm1ZVFZrT0E9PQ==
  url: alpha.kas
  wrappedKey: |
    b3FiS2dxSllrYzUydU1FWEFmOXNyWmdUVHo1WU95L1hCWDl3WkdYcDRmbnpRNGVET0ZNS3JYMEVI
    djVYUGd0VVBYMHRBTDJHbEZCTnhseTdpMjV4UDl0M25GLzlXOVFNZEU1NmprWm5PT2l1Z3Fjb09i
    UDdZMlhCa2JKZXlwcnN4VngwdlovWGxFejlycFZNeUdKQ0JuUGFDM3pQVUhkM1BhQTlucS9xemZE
    dmtXTjVBTUVNWkI0L1I4b3Y5L2drN0dBQ0dubzF6V3lnbFhGaUxrVjBQVkYrZnJWOUtnbWJtLy8w
    clE2NWxWMnQ3eVpOKzkxOTdhUUpqNmRxOWVwazBMUTY5S0xUWDZ6RVIrS3orWmE1TENoZVlxQWd6
    eUYyUXVwTGMrVTFMdElpNC8rYzhpNGsrUzZQY1JoM1BzbHk0Zlp2YVRrTVh5ZFVMMzVsZGJmTzBR
    PT0=
- policyBinding: |
    Wm1ReFkyWm1PREk0WldaaU5qQXpOamszTUdJMk5HSXdNREkyTTJGbE1XUXdaVFl6TUdFeU9EWTJO
    RE01WVRkaE1EbGpPR0l6TUdVM01qVm1ZVFZrT0E9PQ==
  url: beta.kas
  wrappedKey: |
    V3VJRzQvRXhXL0ExaWZsdVVFNUg5SEdzSGxIM0syb3UzdXYzK1MyU2VLckV2b0xUenZTU1loaUIz
    bW1MSVBPU0dUem1naW5tcXkvK3JJSmh3Wk1SNWMyL2pYQks0R2wrVWFwZFAvc09zbi9MWGdvY1FB
    Z0pKdlNrS2dKYzV2b1J4cURhTmQrRjVwQ1YvdEpXT0dvQUE1ZkxldmFiTEduS0FhTlR3RVJTRzlU
    WXJLM1pQY2ZGQnlUbDBkR2lSdmgyeHZwMmM4MWRja2grQTZ6TkxsRjNTV0t3cW8xeXNSZFk1UXhS
    UENHdWlNaUF4RnZNSzVwbjBKZERUSFhwR3NQMUZsOE1UQ1BJWE9vSG92cm9nZDlSZDc5WGt1NVdT
    U3F4cTJZc25BMnBMd2FvbWY5UDRYV2J0YWtSOU5OclJUV3JmZVI5RHRTaWg3SU5YcFlqa0w3cjhR
    PT0=

Split Key Access

If we want to require two different KASes to approve access to the DEK, we use a split with each fraction going to a different KAS. Using a nonce with XOR allows no information to be gained without having (at least some of) each fraction.

- policyBinding: |
    TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP
    VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ==
  sid: split-alpha.kas
  url: alpha.kas
  wrappedKey: |
    SkxtU2QxVDZwMlhNdmQrd2JHSjRPK3p1d005V2xWQTBvR0pwVThzMTR5RWlMMzlza0NQSG9DaEpr
    TXpLTXF1TzdnMUxWS1V3ZUcwa29XTytPNkxvMFhGUnNrTllsdUs1Y1hYRk9CZ1c4MHh4SUtvb2NF
    bmtOMGdxRjgrejZtNElQMmJZcTNVYVloand2SFpZTmYxZGo5dXNTeUw1cWJ3d2U2clNaZWdpM0w1
    VE5oY3I4NmxMNFgvOHZ1b3UwbWtaT1Z2N25CamplckdwdVZHZmlrRk0rV1pIczI2WnpCRExycXZL
    TTJxQjRFbEFTQ3F4L1NOUno4NUpCVTlDa3NybDZ3OUdQNlNzdk9OV3BBR0xtUndmYzU5bUpaZE9M
    cmczSlhaejN6K212R0IzSjdCWkY0NENyWEtZd3BaL0FvRXNHMXRmOUl4SWZJZDU1Z2N4T09rczdB
    PT0=
- policyBinding: |
    WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO
    VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ==
  sid: split-beta.kas
  url: beta.kas
  wrappedKey: |
    aDNEOEUvKzRDZzNGVUVjVEhEbDBoS0hxN2FqbUZMVmEyYUh2UHlTVUl5ZlhSY3Q0dFFCSi9MNTB1
    VlBabXQ0RFZRK3NKYm96MXRRaG9mUWwyMjcwYURVMHNPSzZicUdQZVUyVWNka2tFQXVSQlpLcWtx
    eHhkR0wzOXFQTUtBSFpBYlZkSkUrSkpNY2d5cFlHemQxdVNlNWFTWEFBRTZ2TTdrQ1ZYbXg2Y3dp
    blBQbnF2MFFFOEZDU253b0dPQkw4bnNTWGRiTDVKQkE1S0liZFBMbnVXbW9GNWtmZnFzYngyU1V1
    ZzUxR2tYUjlOYVQxWW1RRDVEU0wrN0ZCQjFXQ3VNKzB5RGhoemZrbFluWVBrdENDTmVlb1RnQkpW
    R2NKTGYzUkdLMVIvOTJKdTYrL0JqWE1YdzVmbExIc2FQR0hodGxxZFQyRFNJVW1NTEY2eWxRYzNn
    PT0=

Hybrid Key Access

Another scneario is we want to allow break-glass with a local HSM or KAS cache, but fall back to remote KASes. This can be accomplished by sharing each split with the HSM.

- policyBinding: |
    TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP
    VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ==
  sid: a
  url: alpha.kas
  wrappedKey: |
    UVRiUnZteDFFc1I3S3pHenBLeVdncEFnVGt6aW9zVm5vc3NDM05mcVNUOS80cDhvdDZwMTJWQU93
    OVVZRUlVN1NYTVZtU3FoSlVjdDlxUlRzWGEyTkttK3NkVzdYVzNldjg2cDFzdWwyRjc5UXN6N0xM
    OTROS2kvelMxQjNDQXBNR1djanhuZ1F4VDNPcVNLRlRRcXBxS2JPYmF1UHhDTGZvZldKazBMVDdF
    WStuRTE0Y2FSTTBhbGp5b0FoL3JQYlljQ2EyTjNYNUhqZTR6ejZNRm1ZanVKUTQyS3Z6Nm5VWHpT
    TVRoMEpuSGFJOW4xZlBDTWNXd1RQYldFS0I3VWVMUGkvVmY1aEdoTFhUTVE3ZTNMVjdGMnlHNzh6
    d1dWeENkb05MKzdsSTFyVDFXTWc3RmVUR3JSSERyV2hOM091Rjk4Uk9SQlpaS2Jrc1pjTjBnZE9n
    PT0=
- policyBinding: |
    WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO
    VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ==
  sid: b
  url: beta.kas
  wrappedKey: |
    SjRlOHNKVDBVNjJ5ODY4NXJqZGMydUhZem5MREc5NEI2YU9ybVgyTHJlazlXa29sVDh5bzZnYjZ4
    RkxGS1pWSzBjV2tpSXR5ZzBBWDVvalBOZWtpM0lEbjlhQnlSQndpWnJ0cjRTNTFPMFZ3bnhXOUc2
    Q21KTWNqQnZQYzJYSGpReUtvOHJIQXhmN3d3WWx3NVU1NXJDdkFRSUEzSHoxQUFjdExLZkVBamh6
    QXhnSTBFVjlPbG5QL0lkMVVtZ2J5ZkRhNTdvTU1MWVlDMXFtem5IVEpZY0dyUUwrTjFpNmxBTUhr
    R0xOOVJ3ZFpBTkd6YlJEWFFkYUFvOUgrY2dmMGlrU1lYWkcwNGdHdWJ2WGpEdlo1cFdUaU51MFVG
    dmh5cjY4UGZTUmNzVjJiQ29sQWZZTllEc3BvckRyMHZMQUY1aTNpc3ZlNWVjaE1BM2thNzNyNXRB
    PT0=
- policyBinding: |
    TkRrNE9HSTRZV001WVROa09HWmhZVGd3TWpOaE5qWTRZMlF3WldZNU4yVmhNRGN3TlRWaE56VTJP
    VFpsT0RsaFl6QmhPVEk0TXpVMk5tUm1OVFk0WkE9PQ==
  sid: a
  url: local.hsm
  wrappedKey: |
    Tnp0U1NXRXVxU0dlVGRLRGJMK3gzMGt6bEsrdE9NdTYyV3lGWFdJbDdNdkx0eHZQWUpCUEhNZG1v
    Y0MvekdzOVZyaFU3S2JvV3hzKy9GWXkrTGgvdlR5WEFnQ1IxSGVsSjFTNzdQYWFvbVdSVG1kak5m
    Y1VOVEZNTUkxMjdoSGVjN3NHUzRLK3U4TlRxMzlHVHdLR2F4Nm16b2NWVnFRVEtMN2xaUWRxalZq
    TzJTejV3YzZ1STlzcHEwYnhKR2piWHlGSkR0V0VqTVowOFRZQ0ROT2N0UmhCT0t5QnA0RVBMVjk2
    dTRSakNvWE0yVWN2aUpkY0doVG9RZjJINnVhb1BSOVcxR2ZNWTdVUDNRSlMyMEpndDdqaG9hcGly
    MXlBSGxBVGdZamxhNm1kbjl4MGljdDBXd2Z1Yjc3VERUMy9VR25oRnYvV1BLaFJWM1BUOStqN2Zn
    PT0=
- policyBinding: |
    WVRneFpUbGhOelpqWm1JNU16aG1ZemhpWXpWbE5qSXpNakZqWlRBeVpqbGhPR1ExTnpZM1pUZzRO
    VGt6WlRRNVlUUTVZelU0Wm1FME5EVXpPRGMzTVE9PQ==
  sid: b
  url: local.hsm
  wrappedKey: |
    Z0dIRmdRMFZNR042VnpCMTBHTjlUcUlvUUpvU0FyUmR3MXhnZld0UEhBaGlkTTVRVE5nZ3JqYk1D
    SFk0MnFidEQrcUErV3lsQmlZdktwMm9QdGU5d1E3T0FONVBRSTlueWpycnp6SCtJd1BkWnI3aXl6
    VzFPL0Nwd0hKblNabXlEOE41UTNna1U2S1lLc0hPdWVsYlYzb2U4OHo1d1UrWTdxbW9PN1B5OHcx
    TnpsMnRqcEV1N2w3eE9oVGNySUgrVDhzUkZBcTV3Yit5RzRRdEFTeU9QeEhiMTNDdjlZUUcxL1FZ
    bGg3TzlkZjdEL3A5YXlybEt0VFF6RzdOTzEydGFSODY2endmSjVFYXA5Slh6T25TZmt3R0JQRUJx
    OVV1WUw4RXR3OFlOOW1TbGxBTmJKblVnVWJ3eENnbDcxQ2JORFRTTGJ1c3FPcGtKakw2SW9naGF3
    PT0=

Summary​

Example"​

keyAccess​

policyBinding​

Key Sharing​

Examples​

Data Encryption Key (DEK)​

Keys for alpha.kas​

Keys for beta.kas​

Keys for local.hsm​

Shared Key Access​

Split Key Access​

Hybrid Key Access​