From f26bb90567e828fca5d01172ae6d020f141b2432 Mon Sep 17 00:00:00 2001 From: Maor Leger Date: Fri, 22 Oct 2021 13:13:56 -0700 Subject: [PATCH] [KeyVault] - Address archboard review feedback (#18319) ## What - return bytes from getRandomBytes - rename KeyReleasePolicy.data to KeyReleasePolicy.encodedPolicy - rename target to targetAttestationToken ## Why These address recent architecture board review comments and will improve the overall experience when using these new APIs. Resolves #18307 Resolves #18317 --- sdk/keyvault/keyvault-keys/CHANGELOG.md | 5 ++++ .../keyvault-keys/review/keyvault-keys.api.md | 11 ++------ .../src/generated/models/index.ts | 2 +- .../src/generated/models/mappers.ts | 2 +- sdk/keyvault/keyvault-keys/src/index.ts | 12 ++++---- sdk/keyvault/keyvault-keys/src/keysModels.ts | 10 +------ sdk/keyvault/keyvault-keys/swagger/README.md | 12 ++++++-- .../test/public/keyClient.hsm.spec.ts | 28 ++++++++++--------- 8 files changed, 41 insertions(+), 41 deletions(-) diff --git a/sdk/keyvault/keyvault-keys/CHANGELOG.md b/sdk/keyvault/keyvault-keys/CHANGELOG.md index f7018ddafbc5..b892d951e9f7 100644 --- a/sdk/keyvault/keyvault-keys/CHANGELOG.md +++ b/sdk/keyvault/keyvault-keys/CHANGELOG.md @@ -8,6 +8,11 @@ ### Breaking Changes +- `KeyClient.getRandomBytes` will now return the generated bytes directly instead of wrapping them in a `RandomBytes` model. + - Since it's no longer used, `RandomBytes` has been removed from the public API. +- `KeyReleasePolicy.data` has been renamed to `KeyReleasePolicy.encodedPolicy`. +- `KeyClient.releaseKey`'s `target` parameter has been renamed to `targetAttestationToken`. + ### Bugs Fixed ### Other Changes diff --git a/sdk/keyvault/keyvault-keys/review/keyvault-keys.api.md b/sdk/keyvault/keyvault-keys/review/keyvault-keys.api.md index fdc82ec86ea1..334e3c6bf4b0 100644 --- a/sdk/keyvault/keyvault-keys/review/keyvault-keys.api.md +++ b/sdk/keyvault/keyvault-keys/review/keyvault-keys.api.md @@ -241,13 +241,13 @@ export class KeyClient { getDeletedKey(name: string, options?: GetDeletedKeyOptions): Promise; getKey(name: string, options?: GetKeyOptions): Promise; getKeyRotationPolicy(name: string, options?: GetKeyRotationPolicyOptions): Promise; - getRandomBytes(count: number, options?: GetRandomBytesOptions): Promise; + getRandomBytes(count: number, options?: GetRandomBytesOptions): Promise; importKey(name: string, key: JsonWebKey_2, options?: ImportKeyOptions): Promise; listDeletedKeys(options?: ListDeletedKeysOptions): PagedAsyncIterableIterator; listPropertiesOfKeys(options?: ListPropertiesOfKeysOptions): PagedAsyncIterableIterator; listPropertiesOfKeyVersions(name: string, options?: ListPropertiesOfKeyVersionsOptions): PagedAsyncIterableIterator; purgeDeletedKey(name: string, options?: PurgeDeletedKeyOptions): Promise; - releaseKey(name: string, target: string, options?: ReleaseKeyOptions): Promise; + releaseKey(name: string, targetAttestationToken: string, options?: ReleaseKeyOptions): Promise; restoreKeyBackup(backup: Uint8Array, options?: RestoreKeyBackupOptions): Promise; rotateKey(name: string, options?: RotateKeyOptions): Promise; updateKeyProperties(name: string, keyVersion: string, options?: UpdateKeyPropertiesOptions): Promise; @@ -300,7 +300,7 @@ export interface KeyProperties { // @public export interface KeyReleasePolicy { contentType?: string; - data?: Uint8Array; + encodedPolicy?: Uint8Array; } // @public @@ -464,11 +464,6 @@ export { PollOperationState } export interface PurgeDeletedKeyOptions extends coreHttp.OperationOptions { } -// @public -export interface RandomBytes { - bytes: Uint8Array; -} - // @public export interface ReleaseKeyOptions extends coreHttp.OperationOptions { algorithm?: KeyExportEncryptionAlgorithm; diff --git a/sdk/keyvault/keyvault-keys/src/generated/models/index.ts b/sdk/keyvault/keyvault-keys/src/generated/models/index.ts index 243e0084491d..02363ee03b7a 100644 --- a/sdk/keyvault/keyvault-keys/src/generated/models/index.ts +++ b/sdk/keyvault/keyvault-keys/src/generated/models/index.ts @@ -51,7 +51,7 @@ export interface KeyReleasePolicy { /** Content type and version of key release policy */ contentType?: string; /** Blob encoding the policy rules under which the key can be released. */ - data?: Uint8Array; + encodedPolicy?: Uint8Array; } /** A KeyBundle consisting of a WebKey plus its attributes. */ diff --git a/sdk/keyvault/keyvault-keys/src/generated/models/mappers.ts b/sdk/keyvault/keyvault-keys/src/generated/models/mappers.ts index a7f108f88509..7e8eba5d0db5 100644 --- a/sdk/keyvault/keyvault-keys/src/generated/models/mappers.ts +++ b/sdk/keyvault/keyvault-keys/src/generated/models/mappers.ts @@ -127,7 +127,7 @@ export const KeyReleasePolicy: coreHttp.CompositeMapper = { name: "String" } }, - data: { + encodedPolicy: { serializedName: "data", type: { name: "Base64Url" diff --git a/sdk/keyvault/keyvault-keys/src/index.ts b/sdk/keyvault/keyvault-keys/src/index.ts index 9f14f145fb97..da2b12a0af7a 100644 --- a/sdk/keyvault/keyvault-keys/src/index.ts +++ b/sdk/keyvault/keyvault-keys/src/index.ts @@ -66,7 +66,6 @@ import { ReleaseKeyResult, KeyReleasePolicy, KeyExportEncryptionAlgorithm, - RandomBytes, GetCryptographyClientOptions, RotateKeyOptions, UpdateKeyRotationPolicyOptions, @@ -153,7 +152,6 @@ export { GetDeletedKeyOptions, GetKeyOptions, GetRandomBytesOptions, - RandomBytes, ImportKeyOptions, JsonWebKey, KeyCurveName, @@ -784,10 +782,10 @@ export class KeyClient { * @param count - The number of bytes to generate between 1 and 128 inclusive. * @param options - The optional parameters. */ - public getRandomBytes(count: number, options: GetRandomBytesOptions = {}): Promise { + public getRandomBytes(count: number, options: GetRandomBytesOptions = {}): Promise { return withTrace("getRandomBytes", options, async (updatedOptions) => { const response = await this.client.getRandomBytes(this.vaultUrl, count, updatedOptions); - return { bytes: response.value! }; + return response.value!; }); } @@ -822,12 +820,12 @@ export class KeyClient { * ``` * * @param name - The name of the key. - * @param target - The attestation assertion for the target of the key release. + * @param targetAttestationToken - The attestation assertion for the target of the key release. * @param options - The optional parameters. */ public releaseKey( name: string, - target: string, + targetAttestationToken: string, options: ReleaseKeyOptions = {} ): Promise { return withTrace("releaseKey", options, async (updatedOptions) => { @@ -836,7 +834,7 @@ export class KeyClient { this.vaultUrl, name, options?.version || "", - target, + targetAttestationToken, { enc: algorithm, nonce, diff --git a/sdk/keyvault/keyvault-keys/src/keysModels.ts b/sdk/keyvault/keyvault-keys/src/keysModels.ts index 6f5362fae33d..bda0c7d91d53 100644 --- a/sdk/keyvault/keyvault-keys/src/keysModels.ts +++ b/sdk/keyvault/keyvault-keys/src/keysModels.ts @@ -286,7 +286,7 @@ export interface KeyReleasePolicy { contentType?: string; /** Blob encoding the policy rules under which the key can be released. */ - data?: Uint8Array; + encodedPolicy?: Uint8Array; } /** @@ -596,14 +596,6 @@ export enum KnownKeyExportEncryptionAlgorithm { export type KeyExportEncryptionAlgorithm = string; /* eslint-enable tsdoc/syntax */ -/** - * Result of the {@link KeyClient.getRandomBytes} operation. - */ -export interface RandomBytes { - /** The random bytes returned by the service. */ - bytes: Uint8Array; -} - /** * Options for {@link KeyClient.getCryptographyClient}. */ diff --git a/sdk/keyvault/keyvault-keys/swagger/README.md b/sdk/keyvault/keyvault-keys/swagger/README.md index 1a586ef27934..f8b85e44e12d 100644 --- a/sdk/keyvault/keyvault-keys/swagger/README.md +++ b/sdk/keyvault/keyvault-keys/swagger/README.md @@ -38,8 +38,6 @@ directive: ### Update swagger enum values for LifetimeActionsType to reflect what the service actually returns -There is an ongoing thread about changing the swagger or returning lowercase values for enum values. - ```yaml directive: - from: swagger-document @@ -48,3 +46,13 @@ directive: $.values[0].value = "Rotate"; $.values[1].value = "Notify"; ``` + +### Rename KeyReleasePolicy.data to KeyReleasePolicy.encodedPolicy + +```yaml +directive: + - from: swagger-document + where: $.definitions.KeyReleasePolicy.properties.data + transform: > + $["x-ms-client-name"] = "encodedPolicy"; +``` diff --git a/sdk/keyvault/keyvault-keys/test/public/keyClient.hsm.spec.ts b/sdk/keyvault/keyvault-keys/test/public/keyClient.hsm.spec.ts index 0578a457e3d3..2d611fe53bd5 100644 --- a/sdk/keyvault/keyvault-keys/test/public/keyClient.hsm.spec.ts +++ b/sdk/keyvault/keyvault-keys/test/public/keyClient.hsm.spec.ts @@ -55,8 +55,8 @@ onVersions({ minVer: "7.2" }).describe( onVersions({ minVer: "7.3-preview" }).describe("getRandomBytes", () => { it("can return the required number of bytes", async () => { const result = await hsmClient.getRandomBytes(10); - assert.exists(result.bytes); - assert.equal(result.bytes.length, 10); + assert.exists(result); + assert.equal(result.length, 10); }); it("returns an error when bytes is out of range", async () => { @@ -106,13 +106,13 @@ onVersions({ minVer: "7.2" }).describe( const keyName = recorder.getUniqueName("exportkey"); const createdKey = await hsmClient.createKey(keyName, "RSA", { exportable: true, - releasePolicy: { data: encodedReleasePolicy }, + releasePolicy: { encodedPolicy: encodedReleasePolicy }, keyOps: ["encrypt", "decrypt"] }); - assert.exists(createdKey.properties.releasePolicy?.data); + assert.exists(createdKey.properties.releasePolicy?.encodedPolicy); assert.isNotEmpty( - JSON.parse(uint8ArrayToString(createdKey.properties.releasePolicy!.data!)) + JSON.parse(uint8ArrayToString(createdKey.properties.releasePolicy!.encodedPolicy!)) ); assert.isTrue(createdKey.properties.exportable); const releaseResult = await hsmClient.releaseKey(keyName, attestation); @@ -125,12 +125,12 @@ onVersions({ minVer: "7.2" }).describe( const importedKey = await hsmClient.importKey(keyName, createRsaKey(), { exportable: true, - releasePolicy: { data: encodedReleasePolicy } + releasePolicy: { encodedPolicy: encodedReleasePolicy } }); - assert.exists(importedKey.properties.releasePolicy?.data); + assert.exists(importedKey.properties.releasePolicy?.encodedPolicy); assert.isNotEmpty( - JSON.parse(uint8ArrayToString(importedKey.properties.releasePolicy!.data!)) + JSON.parse(uint8ArrayToString(importedKey.properties.releasePolicy!.encodedPolicy!)) ); const releaseResult = await hsmClient.releaseKey(keyName, attestation, { version: importedKey.properties.version, @@ -145,7 +145,7 @@ onVersions({ minVer: "7.2" }).describe( const keyName = recorder.getUniqueName("exportkey"); const createdKey = await hsmClient.createKey(keyName, "RSA", { exportable: true, - releasePolicy: { data: encodedReleasePolicy }, + releasePolicy: { encodedPolicy: encodedReleasePolicy }, keyOps: ["encrypt", "decrypt"] }); @@ -165,12 +165,12 @@ onVersions({ minVer: "7.2" }).describe( version: "1.0" }; const updatedKey = await hsmClient.updateKeyProperties(createdKey.name, { - releasePolicy: { data: stringToUint8Array(JSON.stringify(newReleasePolicy)) } + releasePolicy: { encodedPolicy: stringToUint8Array(JSON.stringify(newReleasePolicy)) } }); - assert.exists(updatedKey.properties.releasePolicy?.data); + assert.exists(updatedKey.properties.releasePolicy?.encodedPolicy); const decodedReleasePolicy = JSON.parse( - uint8ArrayToString(updatedKey.properties.releasePolicy!.data!) + uint8ArrayToString(updatedKey.properties.releasePolicy!.encodedPolicy!) ); // Note: the service will parse the policy and return a different shape, for example: { "claim": "sdk-test", "equals": "false" } in this test. @@ -188,7 +188,9 @@ onVersions({ minVer: "7.2" }).describe( it("errors when a key has a release policy but is not exportable", async () => { const keyName = recorder.getUniqueName("policynonexportable"); await assert.isRejected( - hsmClient.createRsaKey(keyName, { releasePolicy: { data: encodedReleasePolicy } }), + hsmClient.createRsaKey(keyName, { + releasePolicy: { encodedPolicy: encodedReleasePolicy } + }), /exportable/i ); });