Skip to main content

Key Access Service

The Key Access Server (KAS) manages the lifecycle of cryptographic keys and provides access to these keys for the encryption and decryption of TDFs. KAS serves as an out-of-the-box Policy Enforcement Point (PEP) for the OpenTDF platform.

RPC Methods​

KAS offers the following RPC methods:

  • PublicKey - Retrieves a public key from KAS. It defaults to rsa:2048 and uses the currently active default key. The key is returned in PEM format by default.

    service/kas/kas.proto
    loading...
    service/kas/kas.proto
    loading...

  • Rewrap - This method takes a key wrapped using a key retrieved from the PublicKey endpoint and rewraps it with a client key. The process succeeds only if the following conditions are met:

    • The policy binding is validated.
    • The authorization service confirms that the entity is allowed access to the TDF.
    service/kas/kas.proto
    loading...
    service/kas/kas.proto
    loading...

How Rewrap Works​

TDF​

KAS TDF Rewrap

  1. The client extracts two pieces of information from the TDF:

    1. Key Access Object (KAO): This contains the wrapped key and the policy binding.
    2. The Policy from the manifest.

  2. The client generates an ephemeral asymmetric key pair, used to wrap the KAO content (such as an AES encryption key that can access the TDF payload) from KAS.

  3. The client builds a RequestBody:

    {
      "keyAccess": "<The Key Access Object>",
      "policy": "<The Policy from the Manifest>",
      "clientPublicKey": "<The public key created in step 2>"
    }

  4. With this RequestBody, the client creates a Signed Request Token, which is a JWT signed with the client's DPoP public key or Ephemeral Key Pair.

    note

    "Demonstration of Proof of Possession" is currently optional due to inconsistencies across identity providers.

    Body of JWT
    {
      "requestBody": "<RequestBody>"
    }

At this point, the client is ready to make the rewrap request. The following is an example request body.

Signed Request Token
{
  "signedRequestToken": "<The JWT>"
}

  1. KAS first verifies the policy binding against the policy passed in the RequestBody. To do this, KAS unwraps the key to retrieve the symmetric key used to sign the original policy. It then generates the HMAC of the policy and compares it to the policy binding in the KAO. If they match, the policy is valid.

    HMAC-SHA256(B64(POLICY), KEY)

  2. If the policy is valid and untampered, KAS calls the Authorization Service to confirm whether the entity is allowed access to the TDF. If authorized, KAS rewraps the symmetric key with the client's public key and returns the newly wrapped key for the client to use in decrypting the TDF.

NanoTDF​

KAS NanoTDF Rewrap

NanoTDF leverages the same KAS Rewrap Endpoint but the request body differs slightly from a TDF Rewrap call.

  1. The client extracts the NanoTDF Header and from that Header extracts the KAS URL.

  2. The client generates an ephemeral asymmetric key pair, used to wrap the shared secret originally generated on NanoTDF creation.

  3. Because NanoTDF doesn't have the concept of a Key Access Object the client builds one. The Key Access Object is then used to help build a RequestBody:

Key Access
 {
  "header": "<nanotdf header>",
  "type": "remote",
  "url": "https://kas.opentdf.io",
  "protocol": "kas"
  }
Request Body
  {
    "requestBody": {
      "algorithm": "ec:secp256r1",
      "keyAccess": "<key access>",
      "clientPublicKey": "<client public key>"
    }
  }

  1. With this RequestBody, the client creates a Signed Request Token, which is a JWT signed with the client's DPoP public key or Ephemeral Key Pair

    note

    "Demonstration of Proof of Possession" is currently optional due to inconsistencies across identity providers.

    Body of JWT
    {
      "requestBody": "<RequestBody>"
    }

At this point, the client is ready to make the rewrap request. The following is an example request body.

Signed Request Token
{
  "signedRequestToken": "<The JWT>"
}
  1. KAS extracts the encrypted policy in the NanoTDF Header and verifies the policy binding.
  • If ECDSA Binding is enabled KAS will verify the use ECDSA to verify the signature otherwise it defaults to comparing the GMAC
  1. If the policy is valid and untampered, KAS calls the Authorization Service to confirm whether the entity is allowed access to the NanoTDF. If authorized, KAS generates a new shared key with the clients ephemeral public key and uses AES-GCM to encrypt the shared secret used to encrypt the NanoTDF payload.