✨ Adds key identifier field to KAO

VERSION

@@ -1 +1 @@
-4.2.1
+4.3.0

api/kas-api.yaml

@@ -45,13 +45,33 @@ paths:
           schema:
             default: rsa:2048
             type: string
+        - name: fmt
+          description: response format
+          in: query
+          schema:
+            default: spki
+            type: string
+            enum:
+              - jwk
+              - spki
+        - name: v
+          description: request version
+          in: query
+          schema:
+            default: '1'
+            type: string
+            enum:
+              - '1'
+              - '2'
       responses:
         "200":
           description: Ok
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/PublicKey"
+                oneOf:
+                  - $ref: "#/components/schemas/PublicKeyV2"
+                  - $ref: "#/components/schemas/PublicKey"
         "404":
           description: Not found
 
@@ -233,6 +253,9 @@ components:
     IV:
       title: Initial vector used to encrypt the ciphertext
       type: string
+    JWK:
+      title: JSON Web Key
+      type: object
     JWT:
       title: JSON Web token
       type: string
@@ -281,6 +304,26 @@ components:
       title: Public key
       type: string
       pattern: '-----BEGIN PUBLIC KEY-----(.|\s)*-----END PUBLIC KEY-----(\s)*'
+    PublicKeyV2:
+      title: Public key and metadata
+      type: object
+      required:
+        - kid
+        - publicKey
+      properties:
+        kid:
+          type: string
+          description: |
+            A stable identifier for the returned public key. This allows 
+            a service to change their public key or to even present multiple
+            public keys with the same algorithm type at a time. This value
+            may be derived from the key data, e.g. a JWK thumbprint or other
+            hash value, or it may be any other unique or generated identifier.
+        publicKey:
+          oneOf:
+            - $ref: "#/components/schemas/PublicKey"
+            - $ref: "#/components/schemas/JWK"
+      pattern: '-----BEGIN PUBLIC KEY-----(.|\s)*-----END PUBLIC KEY-----(\s)*'
     UserId:
       title: User id
       type: string

schema/tdf/KeyAccessObject.md

@@ -9,6 +9,7 @@ A Key Access Object stores not only a wrapped (encrypted) key used to encrypt th
 {
   "type": "wrapped",
   "url": "https:\/\/kas.example.com:5000",
+  "kid": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
   "protocol": "kas",
   "wrappedKey": "OqnOETpwyGE3PVpUpwwWZoJTNW24UMhnXIif0mSnqLVCUPKAAhrjeue11uAXWpb9sD7ZDsmrc9ylmnSKP9vWel8ST68tv6PeVO+CPYUND7cqG2NhUHCLv5Ouys3Klurykvy8\/O3cCLDYl6RDISosxFKqnd7LYD7VnxsYqUns4AW5\/odXJrwIhNO3szZV0JgoBXs+U9bul4tSGNxmYuPOj0RE0HEX5yF5lWlt2vHNCqPlmSBV6+jePf7tOBBsqDq35GxCSHhFZhqCgA3MvnBLmKzVPArtJ1lqg3WUdnWV+o6BUzhDpOIyXzeKn4cK2mCxOXGMP2ck2C1a0sECyB82uw==",
   "policyBinding": "BzmgoIxZzMmIF42qzbdD4Rw30GtdaRSQL2Xlfms1OPs=",
@@ -25,6 +26,7 @@ A Key Access Object stores not only a wrapped (encrypted) key used to encrypt th
 |`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.<p>Possible Values: <dl><dt>remote</dt><dd>The wrapped key (see below) is stored using Virtru infrastructure and is thus not part of the final TDF manifest.</dd><dt>wrapped</dt><dd>Default for TDF 3.x and newer, the wrapped key is stored as part of the manifest.</dd><dt>remoteWrapped</dt><dd>Allows management of customer hosted keys, such as with a *Customer Key Server*. This feature is available as an upgrade path.</dd></dl>|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.|Recommended|
 |`protocol`|String|Protocol being used. Currently only `kas` is supported|Yes|
 |`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|This 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. <p>This is Base64 encoding of HMAC(POLICY,KEY), where: <dl><dt>POLICY</dt><dd>`base64(policyjson)` that is in the “encryptionInformation/policy”</dd><dt>HMAC</dt><dd>HMAC SHA256 (default, but can be specified in the alg field described above)</dd><dt>KEY</dt><dd>Whichever Key Split or Key that is available to the KAS (e.g. the underlying AES 256 key in the wrappedKey.</dd></dl>|Yes|