Share via


unwrap Key - unwrap Key

Unwraps a symmetric key using the specified key that was initially used for wrapping that key.
The UNWRAP operation supports decryption of a symmetric key using the target key encryption key. This operation is the reverse of the WRAP operation. The UNWRAP operation applies to asymmetric and symmetric keys stored in Azure Key Vault since it uses the private portion of the key. This operation requires the keys/unwrapKey permission.

POST {vaultBaseUrl}/keys/{key-name}/{key-version}/unwrapkey?api-version=7.4

URI Parameters

Name In Required Type Description
key-name
path True

string

The name of the key.

key-version
path True

string

The version of the key.

vaultBaseUrl
path True

string

The vault name, for example https://myvault.vault.azure.net.

api-version
query True

string

Client API version.

Request Body

Name Required Type Description
alg True

JsonWebKeyEncryptionAlgorithm

minLength: 1

algorithm identifier

value True

string (base64url)

aad

string (base64url)

Additional data to authenticate but not encrypt/decrypt when using authenticated crypto algorithms.

iv

string (base64url)

Cryptographically random, non-repeating initialization vector for symmetric algorithms.

tag

string (base64url)

The tag to authenticate when performing decryption with an authenticated algorithm.

Responses

Name Type Description
200 OK

KeyOperationResult

The unwrapped symmetric key.

Other Status Codes

KeyVaultError

Key Vault error response describing why the operation failed.

Examples

Unwrapkey

Sample request

POST https://myvault.vault.azure.net//keys/sdktestkey/0698c2156c1a4e1da5b6bab6f6422fd6/unwrapkey?api-version=7.4

{
  "alg": "RSA1_5",
  "value": "khwIe26NuAZazS7upywDBpGRmRNMW5-4h_JQKxOdB78nYVxZWnBXwCxOv7a3Sr_mCjiVzKsoQQZwL-CJzhYa0512tfYem56zls5a44y5QsdcfvuSzOvpthVhA9XkEfCJSqSY_sip5d8BelT_w_ikvd_8KqiQ_0H54RqYUN8svCpu28paHgBocHFNXTQ9NtU9ec2qgESXk7Jp4OTy9HJtQJavKDUqTJ3YmtLxUgsgBCe0FNMHUSEYC0Ys6PavYzdTwIzYCq84idmAxJOj-O_6eALJFH2sDTOQYHjzOae2t8eFmw6C-t55qjrCI91a9mUJEGPhYixiG4gR4PaEJ7wGvw"
}

Sample response

{
  "kid": "https://myvault.vault.azure.net/keys/sdktestkey/0698c2156c1a4e1da5b6bab6f6422fd6",
  "value": "ovQIlbB0DgWhZA7sgkPxbg9H-Ly-VlNGPSgGrrZvlIo"
}

Definitions

Name Description
Error

The key vault server error.

JsonWebKeyEncryptionAlgorithm

algorithm identifier

KeyOperationResult

The key operation result.

KeyOperationsParameters

The key operations parameters.

KeyVaultError

The key vault error exception.

Error

The key vault server error.

Name Type Description
code

string

The error code.

innererror

Error

The key vault server error.

message

string

The error message.

JsonWebKeyEncryptionAlgorithm

algorithm identifier

Value Description
RSA-OAEP
RSA-OAEP-256
RSA1_5
A128GCM
A192GCM
A256GCM
A128KW
A192KW
A256KW
A128CBC
A192CBC
A256CBC
A128CBCPAD
A192CBCPAD
A256CBCPAD

KeyOperationResult

The key operation result.

Name Type Description
aad

string (base64url)

iv

string (base64url)

kid

string

Key identifier

tag

string (base64url)

value

string (base64url)

KeyOperationsParameters

The key operations parameters.

Name Type Description
aad

string (base64url)

Additional data to authenticate but not encrypt/decrypt when using authenticated crypto algorithms.

alg

JsonWebKeyEncryptionAlgorithm

minLength: 1

algorithm identifier

iv

string (base64url)

Cryptographically random, non-repeating initialization vector for symmetric algorithms.

tag

string (base64url)

The tag to authenticate when performing decryption with an authenticated algorithm.

value

string (base64url)

KeyVaultError

The key vault error exception.

Name Type Description
error

Error

The key vault server error.