/// <summary>
/// Create a Client Encryption Key used to Encrypt data.
/// </summary>
/// <param name="database">Regular cosmos database.</param>
/// <param name="clientEncryptionKeyId"> Client Encryption Key id.</param>
/// <param name="dataEncryptionKeyAlgorithm"> Encryption Algorthm. </param>
/// <param name="encryptionKeyWrapMetadata"> EncryptionKeyWrapMetadata.</param>
/// <param name="cancellationToken"> cancellation token </param>
/// <returns>Container to perform operations supporting client-side encryption / decryption.</returns>
/// <example>
/// This example shows how to create a new Client Encryption Key.
///
/// <code language="c#">
/// <![CDATA[
/// ClientEncryptionKeyResponse response = await this.cosmosDatabase.CreateClientEncryptionKeyAsync(
/// "testKey",
/// DataEncryptionKeyAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
/// new EncryptionKeyWrapMetadata("metadataName", "MetadataValue"));
/// ]]>
/// </code>
/// </example>
public static async Task <ClientEncryptionKeyResponse> CreateClientEncryptionKeyAsync(
this Database database,
string clientEncryptionKeyId,
DataEncryptionKeyAlgorithm dataEncryptionKeyAlgorithm,
EncryptionKeyWrapMetadata encryptionKeyWrapMetadata,
CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
if (string.IsNullOrWhiteSpace(clientEncryptionKeyId))
{
throw new ArgumentNullException(nameof(clientEncryptionKeyId));
}
string encryptionAlgorithm = dataEncryptionKeyAlgorithm.ToString();
if (!string.Equals(encryptionAlgorithm, DataEncryptionKeyAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256.ToString()))
{
throw new ArgumentException($"Invalid Encryption Algorithm '{encryptionAlgorithm}' passed. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
}
if (encryptionKeyWrapMetadata == null)
{
throw new ArgumentNullException(nameof(encryptionKeyWrapMetadata));
}
EncryptionCosmosClient encryptionCosmosClient;
if (database is EncryptionDatabase encryptionDatabase)
{
encryptionCosmosClient = encryptionDatabase.EncryptionCosmosClient;
}
else
{
throw new ArgumentException("Creating a ClientEncryptionKey resource requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
}
EncryptionKeyStoreProvider encryptionKeyStoreProvider = encryptionCosmosClient.EncryptionKeyStoreProvider;
KeyEncryptionKey keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
encryptionKeyWrapMetadata.Name,
encryptionKeyWrapMetadata.Value,
encryptionKeyStoreProvider);
ProtectedDataEncryptionKey protectedDataEncryptionKey = new ProtectedDataEncryptionKey(
clientEncryptionKeyId,
keyEncryptionKey);
byte[] wrappedDataEncryptionKey = protectedDataEncryptionKey.EncryptedValue;
ClientEncryptionKeyProperties clientEncryptionKeyProperties = new ClientEncryptionKeyProperties(
clientEncryptionKeyId,
encryptionAlgorithm,
wrappedDataEncryptionKey,
encryptionKeyWrapMetadata);
ClientEncryptionKeyResponse clientEncryptionKeyResponse = await database.CreateClientEncryptionKeyAsync(
clientEncryptionKeyProperties,
cancellationToken : cancellationToken);
return(clientEncryptionKeyResponse);
}
/// <summary>
/// Creates a client encryption key.
/// This generates a cryptographically random data encryption key, wraps it using
/// information provided in the encryptionKeyWrapMetadata using the IKeyEncryptionKeyResolver instance configured on the client,
/// and saves the wrapped data encryption key along with the encryptionKeyWrapMetadata at the Cosmos DB service.
/// </summary>
/// <param name="database">Database supporting encryption in which the client encryption key properties will be saved.</param>
/// <param name="clientEncryptionKeyId">Identifier for the client encryption key.</param>
/// <param name="encryptionAlgorithm">Algorithm which will be used for encryption with this key.</param>
/// <param name="encryptionKeyWrapMetadata">Metadata used to wrap the data encryption key with a key encryption key.</param>
/// <param name="cancellationToken">Token for request cancellation.</param>
/// <returns>Response from the Cosmos DB service with <see cref="ClientEncryptionKeyProperties"/>.</returns>
/// <example>
/// This example shows how to create a client encryption key.
///
/// <code language="c#">
/// <![CDATA[
/// Azure.Core.TokenCredential tokenCredential = new Azure.Identity.DefaultAzureCredential();
/// Azure.Core.Cryptography.IKeyEncryptionKeyResolver keyResolver = new Azure.Security.KeyVault.Keys.Cryptography.KeyResolver(tokenCredential);
/// CosmosClient client = (new CosmosClient(endpoint, authKey)).WithEncryption(keyResolver, KeyEncryptionKeyResolverName.AzureKeyVault);
///
/// EncryptionKeyWrapMetadata wrapMetadata = new EncryptionKeyWrapMetadata(
/// type: KeyEncryptionKeyResolverName.AzureKeyVault,
/// name: "myKek",
/// value: "https://contoso.vault.azure.net/keys/myKek/78deebed173b48e48f55abf87ed4cf71",
/// algorithm: Azure.Security.KeyVault.Keys.Cryptography.EncryptionAlgorithm.RsaOaep.ToString());
///
/// ClientEncryptionKeyResponse response = await client.GetDatabase("databaseId").CreateClientEncryptionKeyAsync(
/// "myCek",
/// DataEncryptionAlgorithm.AeadAes256CbcHmacSha256,
/// wrapMetadata);
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
/// </remarks>
public static async Task <ClientEncryptionKeyResponse> CreateClientEncryptionKeyAsync(
this Database database,
string clientEncryptionKeyId,
string encryptionAlgorithm,
EncryptionKeyWrapMetadata encryptionKeyWrapMetadata,
CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
if (string.IsNullOrWhiteSpace(clientEncryptionKeyId))
{
throw new ArgumentNullException(nameof(clientEncryptionKeyId));
}
if (!string.Equals(encryptionAlgorithm, DataEncryptionAlgorithm.AeadAes256CbcHmacSha256))
{
throw new ArgumentException($"Invalid encryption algorithm '{encryptionAlgorithm}' passed. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
}
if (encryptionKeyWrapMetadata == null)
{
throw new ArgumentNullException(nameof(encryptionKeyWrapMetadata));
}
if (encryptionKeyWrapMetadata.Algorithm != EncryptionKeyStoreProviderImpl.RsaOaepWrapAlgorithm)
{
throw new ArgumentException($"Invalid key wrap algorithm '{encryptionKeyWrapMetadata.Algorithm}' passed. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
}
EncryptionCosmosClient encryptionCosmosClient = database is EncryptionDatabase encryptionDatabase
? encryptionDatabase.EncryptionCosmosClient
: throw new ArgumentException("Creating a client encryption key requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
if (!string.Equals(encryptionKeyWrapMetadata.Type, encryptionCosmosClient.KeyEncryptionKeyResolverName))
{
throw new ArgumentException($"The Type of the EncryptionKeyWrapMetadata '{encryptionKeyWrapMetadata.Type}' does not match"
+ $" with the keyEncryptionKeyResolverName '{encryptionCosmosClient.KeyEncryptionKeyResolverName}' configured."
+ " Please refer to https://aka.ms/CosmosClientEncryption for more details.");
}
KeyEncryptionKey keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
encryptionKeyWrapMetadata.Name,
encryptionKeyWrapMetadata.Value,
encryptionCosmosClient.EncryptionKeyStoreProviderImpl);
ProtectedDataEncryptionKey protectedDataEncryptionKey = new ProtectedDataEncryptionKey(
clientEncryptionKeyId,
keyEncryptionKey);
byte[] wrappedDataEncryptionKey = protectedDataEncryptionKey.EncryptedValue;
// cache it.
ProtectedDataEncryptionKey.GetOrCreate(
clientEncryptionKeyId,
keyEncryptionKey,
wrappedDataEncryptionKey);
ClientEncryptionKeyProperties clientEncryptionKeyProperties = new ClientEncryptionKeyProperties(
clientEncryptionKeyId,
encryptionAlgorithm,
wrappedDataEncryptionKey,
encryptionKeyWrapMetadata);
ClientEncryptionKeyResponse clientEncryptionKeyResponse = await database.CreateClientEncryptionKeyAsync(
clientEncryptionKeyProperties,
cancellationToken : cancellationToken);
return(clientEncryptionKeyResponse);
}
/// <summary>
/// Rewrap an existing Client Encryption Key.
/// </summary>
/// <param name="database">Regular cosmos database.</param>
/// <param name="clientEncryptionKeyId"> Client Encryption Key id.</param>
/// <param name="newEncryptionKeyWrapMetadata"> EncryptionKeyWrapMetadata.</param>
/// <param name="cancellationToken"> cancellation token </param>
/// <returns>Container to perform operations supporting client-side encryption / decryption.</returns>
/// <example>
/// This example shows how to rewrap a Client Encryption Key.
///
/// <code language="c#">
/// <![CDATA[
/// ClientEncryptionKeyResponse response = await this.cosmosDatabase.RewrapClientEncryptionKeyAsync(
/// "keyToRewrap",
/// new EncryptionKeyWrapMetadata("metadataName", "UpdatedMetadataValue")));
/// ]]>
/// </code>
/// </example>
public static async Task <ClientEncryptionKeyResponse> RewrapClientEncryptionKeyAsync(
this Database database,
string clientEncryptionKeyId,
EncryptionKeyWrapMetadata newEncryptionKeyWrapMetadata,
CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
if (string.IsNullOrWhiteSpace(clientEncryptionKeyId))
{
throw new ArgumentNullException(nameof(clientEncryptionKeyId));
}
if (newEncryptionKeyWrapMetadata == null)
{
throw new ArgumentNullException(nameof(newEncryptionKeyWrapMetadata));
}
ClientEncryptionKey clientEncryptionKey = database.GetClientEncryptionKey(clientEncryptionKeyId);
EncryptionCosmosClient encryptionCosmosClient;
if (database is EncryptionDatabase encryptionDatabase)
{
encryptionCosmosClient = encryptionDatabase.EncryptionCosmosClient;
}
else
{
throw new ArgumentException("Rewraping a ClientEncryptionKey requires the use of an encryption - enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details. ");
}
EncryptionKeyStoreProvider encryptionKeyStoreProvider = encryptionCosmosClient.EncryptionKeyStoreProvider;
ClientEncryptionKeyProperties clientEncryptionKeyProperties = await clientEncryptionKey.ReadAsync(cancellationToken : cancellationToken);
RequestOptions requestOptions = new RequestOptions
{
IfMatchEtag = clientEncryptionKeyProperties.ETag,
};
KeyEncryptionKey keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
clientEncryptionKeyProperties.EncryptionKeyWrapMetadata.Name,
clientEncryptionKeyProperties.EncryptionKeyWrapMetadata.Value,
encryptionKeyStoreProvider);
byte[] unwrappedKey = keyEncryptionKey.DecryptEncryptionKey(clientEncryptionKeyProperties.WrappedDataEncryptionKey);
keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
newEncryptionKeyWrapMetadata.Name,
newEncryptionKeyWrapMetadata.Value,
encryptionKeyStoreProvider);
byte[] rewrappedKey = keyEncryptionKey.EncryptEncryptionKey(unwrappedKey);
clientEncryptionKeyProperties = new ClientEncryptionKeyProperties(
clientEncryptionKeyId,
clientEncryptionKeyProperties.EncryptionAlgorithm,
rewrappedKey,
newEncryptionKeyWrapMetadata);
ClientEncryptionKeyResponse clientEncryptionKeyResponse = await clientEncryptionKey.ReplaceAsync(
clientEncryptionKeyProperties,
requestOptions,
cancellationToken : cancellationToken);
return(clientEncryptionKeyResponse);
}
/// <summary>
/// Rewraps a client encryption key.
/// This wraps the existing data encryption key using information provided in the newEncryptionKeyWrapMetadata
/// using the IKeyEncryptionKeyResolver instance configured on the client,
/// and saves the wrapped data encryption key along with the newEncryptionKeyWrapMetadata at the Cosmos DB service.
/// </summary>
/// <param name="database">Database supporting encryption in which the client encryption key properties will be updated.</param>
/// <param name="clientEncryptionKeyId">Identifier for the client encryption key.</param>
/// <param name="newEncryptionKeyWrapMetadata">Metadata used to wrap the data encryption key with a key encryption key.</param>
/// <param name="cancellationToken">Token for request cancellation.</param>
/// <returns>Response from the Cosmos DB service with updated <see cref="ClientEncryptionKeyProperties"/>.</returns>
/// <example>
/// This example shows how to rewrap a client encryption key.
///
/// <code language="c#">
/// <![CDATA[
/// Azure.Core.TokenCredential tokenCredential = new Azure.Identity.DefaultAzureCredential();
/// Azure.Core.Cryptography.IKeyEncryptionKeyResolver keyResolver = new Azure.Security.KeyVault.Keys.Cryptography.KeyResolver(tokenCredential);
/// CosmosClient client = (new CosmosClient(endpoint, authKey)).WithEncryption(keyResolver, KeyEncryptionKeyResolverName.AzureKeyVault);
///
/// EncryptionKeyWrapMetadata wrapMetadataForNewKeyVersion = new EncryptionKeyWrapMetadata(
/// type: KeyEncryptionKeyResolverName.AzureKeyVault,
/// name: "myKek",
/// value: "https://contoso.vault.azure.net/keys/myKek/0698c2156c1a4e1da5b6bab6f6422fd6",
/// algorithm: Azure.Security.KeyVault.Keys.Cryptography.EncryptionAlgorithm.RsaOaep.ToString());
///
/// ClientEncryptionKeyResponse response = await client.GetDatabase("databaseId").RewrapClientEncryptionKeyAsync(
/// "myCek",
/// wrapMetadataForNewKeyVersion);
/// ]]>
/// </code>
/// </example>
/// <remarks>
/// See <see href="https://aka.ms/CosmosClientEncryption">client-side encryption documentation</see> for more details.
/// </remarks>
public static async Task <ClientEncryptionKeyResponse> RewrapClientEncryptionKeyAsync(
this Database database,
string clientEncryptionKeyId,
EncryptionKeyWrapMetadata newEncryptionKeyWrapMetadata,
CancellationToken cancellationToken = default)
{
cancellationToken.ThrowIfCancellationRequested();
if (string.IsNullOrWhiteSpace(clientEncryptionKeyId))
{
throw new ArgumentNullException(nameof(clientEncryptionKeyId));
}
if (newEncryptionKeyWrapMetadata == null)
{
throw new ArgumentNullException(nameof(newEncryptionKeyWrapMetadata));
}
if (newEncryptionKeyWrapMetadata.Algorithm != EncryptionKeyStoreProviderImpl.RsaOaepWrapAlgorithm)
{
throw new ArgumentException($"Invalid key wrap algorithm '{newEncryptionKeyWrapMetadata.Algorithm}' passed. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
}
ClientEncryptionKey clientEncryptionKey = database.GetClientEncryptionKey(clientEncryptionKeyId);
EncryptionCosmosClient encryptionCosmosClient = database is EncryptionDatabase encryptionDatabase
? encryptionDatabase.EncryptionCosmosClient
: throw new ArgumentException("Rewrapping a client encryption key requires the use of an encryption-enabled client. Please refer to https://aka.ms/CosmosClientEncryption for more details.");
if (!string.Equals(newEncryptionKeyWrapMetadata.Type, encryptionCosmosClient.KeyEncryptionKeyResolverName))
{
throw new ArgumentException($"The Type of the EncryptionKeyWrapMetadata '{newEncryptionKeyWrapMetadata.Type}' does not match"
+ $" with the keyEncryptionKeyResolverName '{encryptionCosmosClient.KeyEncryptionKeyResolverName}' configured."
+ " Please refer to https://aka.ms/CosmosClientEncryption for more details.");
}
ClientEncryptionKeyProperties clientEncryptionKeyProperties = await clientEncryptionKey.ReadAsync(cancellationToken : cancellationToken);
RequestOptions requestOptions = new RequestOptions
{
IfMatchEtag = clientEncryptionKeyProperties.ETag,
};
KeyEncryptionKey keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
clientEncryptionKeyProperties.EncryptionKeyWrapMetadata.Name,
clientEncryptionKeyProperties.EncryptionKeyWrapMetadata.Value,
encryptionCosmosClient.EncryptionKeyStoreProviderImpl);
byte[] unwrappedKey = keyEncryptionKey.DecryptEncryptionKey(clientEncryptionKeyProperties.WrappedDataEncryptionKey);
keyEncryptionKey = KeyEncryptionKey.GetOrCreate(
newEncryptionKeyWrapMetadata.Name,
newEncryptionKeyWrapMetadata.Value,
encryptionCosmosClient.EncryptionKeyStoreProviderImpl);
byte[] rewrappedKey = keyEncryptionKey.EncryptEncryptionKey(unwrappedKey);
clientEncryptionKeyProperties = new ClientEncryptionKeyProperties(
clientEncryptionKeyId,
clientEncryptionKeyProperties.EncryptionAlgorithm,
rewrappedKey,
newEncryptionKeyWrapMetadata);
ClientEncryptionKeyResponse clientEncryptionKeyResponse = await clientEncryptionKey.ReplaceAsync(
clientEncryptionKeyProperties,
requestOptions,
cancellationToken : cancellationToken);
return(clientEncryptionKeyResponse);
}
