Cifrado del lado de cliente y Azure Key Vault para Microsoft Azure StorageClient-Side Encryption and Azure Key Vault for Microsoft Azure Storage

Información generalOverview

La Biblioteca de cliente de Azure Storage para .NET permite tanto el cifrado de datos dentro de las aplicaciones de cliente antes de cargarlos en Azure Storage, como el descifrado de datos mientras estos se descargan al cliente.The Azure Storage Client Library for .NET supports encrypting data within client applications before uploading to Azure Storage, and decrypting data while downloading to the client. Asimismo, la biblioteca también admite la integración con Azure Key Vault para la administración de claves de la cuenta de almacenamiento.The library also supports integration with Azure Key Vault for storage account key management.

Para ver un tutorial paso a paso que le guíe por el proceso de cifrado de blobs mediante el cifrado de cliente y Azure Key Vault, consulte Cifrado y descifrado de blobs en Microsoft Azure Storage con Azure Key Vault.For a step-by-step tutorial that leads you through the process of encrypting blobs using client-side encryption and Azure Key Vault, see Encrypt and decrypt blobs in Microsoft Azure Storage using Azure Key Vault.

Para el cifrado del lado cliente con Java, consulte el artículo Cifrado del lado cliente con Java para Microsoft Azure Storage.For client-side encryption with Java, see Client-Side Encryption with Java for Microsoft Azure Storage.

Cifrado y descifrado a través de la técnica de sobresEncryption and decryption via the envelope technique

El proceso de cifrado y descifrado sigue la técnica de sobres.The processes of encryption and decryption follow the envelope technique.

Cifrado a través de la técnica de sobresEncryption via the envelope technique

El cifrado mediante la técnica de sobres funciona de la siguiente manera:Encryption via the envelope technique works in the following way:

  1. La biblioteca de cliente de almacenamiento de Azure genera una clave de cifrado de contenido (CEK), que es una clave simétrica de un solo uso.The Azure storage client library generates a content encryption key (CEK), which is a one-time-use symmetric key.

  2. Los datos de usuario se cifran mediante esta CEK.User data is encrypted using this CEK.

  3. Se encapsula la CEK (cifrada) con la clave de cifrado de clave (KEK).The CEK is then wrapped (encrypted) using the key encryption key (KEK). La KEK se identifica mediante un identificador de clave y puede ser un par de clave asimétrico o una clave simétrica que puede administrarse de forma local o guardarse en Azure Key Vault.The KEK is identified by a key identifier and can be an asymmetric key pair or a symmetric key and can be managed locally or stored in Azure Key Vaults.

    La propia biblioteca de cliente de almacenamiento no tiene nunca acceso a la KEK.The storage client library itself never has access to KEK. La biblioteca invoca el algoritmo de encapsulado de clave proporcionado por Key Vault.The library invokes the key wrapping algorithm that is provided by Key Vault. Los usuarios pueden elegir utilizar proveedores personalizados para el ajuste y desajuste clave si lo desean.Users can choose to use custom providers for key wrapping/unwrapping if desired.

  4. A continuación, se cargan los datos cifrados en el servicio Azure Storage.The encrypted data is then uploaded to the Azure Storage service. La clave encapsulada y algunos metadatos adicionales de cifrado se almacenan como metadatos (en un blob) o se interpolan con los datos cifrados (cola de mensajes y las entidades de tabla).The wrapped key along with some additional encryption metadata is either stored as metadata (on a blob) or interpolated with the encrypted data (queue messages and table entities).

Descifrado a través de la técnica de sobresDecryption via the envelope technique

El descifrado mediante la técnica de sobres funciona de la siguiente manera:Decryption via the envelope technique works in the following way:

  1. La biblioteca de cliente asume que el usuario está administrando la clave de cifrado de claves (KEK), ya sea localmente o en almacenes de claves de Azure.The client library assumes that the user is managing the key encryption key (KEK) either locally or in Azure Key Vaults. El usuario no necesita conocer la clave específica que se usó para el cifrado.The user does not need to know the specific key that was used for encryption. En su lugar, se puede configurar y usar una resolución de clave que resuelva distintos identificadores de clave para las claves.Instead, a key resolver which resolves different key identifiers to keys can be set up and used.
  2. La biblioteca de cliente descarga los datos cifrados junto con cualquier material de cifrado que esté almacenado en el servicio.The client library downloads the encrypted data along with any encryption material that is stored on the service.
  3. A continuación, la clave de cifrado de contenido encapsulado (CEK) se desencapsula (descifra) usando la clave de cifrado de claves (KEK).The wrapped content encryption key (CEK) is then unwrapped (decrypted) using the key encryption key (KEK). Aquí nuevamente, la biblioteca de cliente no tiene acceso a la KEK.Here again, the client library does not have access to KEK. Simplemente, invoca el algoritmo de desencapsulado personalizado o el del proveedor de Key Vault.It simply invokes the custom or Key Vault provider's unwrapping algorithm.
  4. La clave de cifrado de contenido (CEK) se usa entonces para descifrar los datos cifrados del usuario.The content encryption key (CEK) is then used to decrypt the encrypted user data.

Mecanismo de cifradoEncryption Mechanism

La biblioteca de cliente de almacenamiento usa AES para cifrar los datos del usuario.The storage client library uses AES in order to encrypt user data. En concreto, emplea el modo Cipher Block Chaining (CBC) con AES.Specifically, Cipher Block Chaining (CBC) mode with AES. Cada servicio funciona de forma ligeramente diferente, por lo que describiremos aquí cada uno de ellos.Each service works somewhat differently, so we will discuss each of them here.

Datos BLOBBlobs

La biblioteca de cliente solo admite actualmente el cifrado de blobs completos.The client library currently supports encryption of whole blobs only. Precisamente, se admite el cifrado cuando los usuarios emplean los métodos UploadFrom u OpenWrite.Specifically, encryption is supported when users use the UploadFrom methods or the OpenWrite method. En el caso de las descargas, se admiten tanto las descargas de intervalo como las completas.For downloads, both complete and range downloads are supported.

Durante el cifrado, la biblioteca de cliente generará un vector de inicialización (IV) aleatorio de 16 bytes, junto con una clave de cifrado de contenido (CEK) aleatoria de 32 bytes, y realiza el cifrado de sobres de los datos de blob con esta información.During encryption, the client library will generate a random Initialization Vector (IV) of 16 bytes, together with a random content encryption key (CEK) of 32 bytes, and perform envelope encryption of the blob data using this information. Posteriormente, la CEK encapsulada y algunos metadatos de cifrado adicionales se almacenan como metadatos de blob junto con el objeto blob cifrado en el servicio.The wrapped CEK and some additional encryption metadata are then stored as blob metadata along with the encrypted blob on the service.

Advertencia

Si está modificando o cargando sus propios metadatos para el blob, deberá asegurarse de que estos metadatos se conserven.If you are editing or uploading your own metadata for the blob, you need to ensure that this metadata is preserved. Si carga nuevos metadatos sin estos metadatos, la CEK encapsulada, IV y otros metadatos se perderán y el contenido del blob nunca podrá recuperarse nuevamente.If you upload new metadata without this metadata, the wrapped CEK, IV, and other metadata will be lost and the blob content will never be retrievable again.

Descargar un blob cifrado implica recuperar el contenido del blob completo mediante los cómodos métodos DownloadTo/BlobReadStream.Downloading an encrypted blob involves retrieving the content of the entire blob using the DownloadTo/BlobReadStream convenience methods. La CEK encapsulada se desencapsula y se utiliza junto con el vector de inicialización (que se almacena como metadatos de blob, en este caso) para devolver los datos descifrados a los usuarios.The wrapped CEK is unwrapped and used together with the IV (stored as blob metadata in this case) to return the decrypted data to the users.

Descargar un intervalo arbitrario (métodosDownloadRange) en el blob cifrado, implica ajustar el intervalo proporcionado por los usuarios para obtener una pequeña cantidad de datos adicionales que puedan usarse para descifrar correctamente el intervalo solicitado.Downloading an arbitrary range (DownloadRange methods) in the encrypted blob involves adjusting the range provided by users in order to get a small amount of additional data that can be used to successfully decrypt the requested range.

Todos los tipos de blobs (blobs en bloques, blobs de anexión) se pueden cifrar y descifrar usando este esquema.All blob types (block blobs, page blobs, and append blobs) can be encrypted/decrypted using this scheme.

ColasQueues

Dado que la cola de mensajes puede tener cualquier formato, la biblioteca de cliente define un formato personalizado que incluye el vector de inicialización (IV) y la clave de cifrado de contenido (CEK) cifrada en el texto del mensaje.Since queue messages can be of any format, the client library defines a custom format that includes the Initialization Vector (IV) and the encrypted content encryption key (CEK) in the message text.

Durante el cifrado, la biblioteca de cliente genera un vector de inicialización aleatorio de 16 bytes junto con una CEK aleatoria de 32 bytes y realiza el cifrado de sobres del texto del mensaje de cola con esta información.During encryption, the client library generates a random IV of 16 bytes along with a random CEK of 32 bytes and performs envelope encryption of the queue message text using this information. La CEK encapsulada y algunos metadatos de cifrado adicionales se incluyen entonces en el mensaje de cola cifrado.The wrapped CEK and some additional encryption metadata are then added to the encrypted queue message. Este mensaje modificado (que se muestra a continuación) se almacena en el servicio.This modified message (shown below) is stored on the service.

<MessageText>{"EncryptedMessageContents":"6kOu8Rq1C3+M1QO4alKLmWthWXSmHV3mEfxBAgP9QGTU++MKn2uPq3t2UjF1DO6w","EncryptionData":{…}}</MessageText>

Durante el descifrado, la clave encapsulada se extrae del mensaje de cola y se desencapsula.During decryption, the wrapped key is extracted from the queue message and unwrapped. El vector de inicialización también se extrae del mensaje de cola y se utiliza junto con la clave desencapsulada para descifrar los datos de mensaje de cola.The IV is also extracted from the queue message and used along with the unwrapped key to decrypt the queue message data. Tenga en cuenta que los metadatos de cifrado son pequeños (menos de 500 bytes), por lo que, aunque se tienen en cuenta para el límite de 64 KB para un mensaje de la cola, el impacto debería ser fácil de administrar.Note that the encryption metadata is small (under 500 bytes), so while it does count toward the 64KB limit for a queue message, the impact should be manageable.

TablasTables

La biblioteca de cliente admite el cifrado de propiedades de entidad para operaciones de insertar y reemplazar.The client library supports encryption of entity properties for insert and replace operations.

Nota

Las operaciones de combinación no se admiten actualmente.Merge is not currently supported. Puesto que un subconjunto de propiedades puede haberse cifrado previamente con una clave distinta, si simplemente se combinan las nuevas propiedades y se actualizan los metadatos, se producirá una pérdida de datos.Since a subset of properties may have been encrypted previously using a different key, simply merging the new properties and updating the metadata will result in data loss. Para realizar una combinación es necesario realizar llamadas de servicio adicionales para leer la entidad existente desde el servicio. También puede usar una nueva clave por propiedad. Ninguno de estos procedimientos es adecuado por motivos de rendimiento.Merging either requires making extra service calls to read the pre-existing entity from the service, or using a new key per property, both of which are not suitable for performance reasons.

El cifrado de datos de tabla funciona de la siguiente forma:Table data encryption works as follows:

  1. Los usuarios especifican las propiedades que se van a cifrar.Users specify the properties to be encrypted.
  2. La biblioteca de cliente genera un vector de inicialización (IV) aleatorio de 16 bytes junto con una clave de cifrado de contenido (CEK) aleatoria de 32 bytes para cada entidad. Después, realiza el cifrado de sobres en las propiedades individuales que se van a cifrar derivando un nuevo vector de inicialización por propiedad.The client library generates a random Initialization Vector (IV) of 16 bytes along with a random content encryption key (CEK) of 32 bytes for every entity, and performs envelope encryption on the individual properties to be encrypted by deriving a new IV per property. La propiedad de cifrado se almacena como datos binarios.The encrypted property is stored as binary data.
  3. La CEK encapsulada y algunos metadatos de cifrado adicional se almacenan posteriormente como dos propiedades reservadas adicionales.The wrapped CEK and some additional encryption metadata are then stored as two additional reserved properties. La primera propiedad reservada (_ClientEncryptionMetadata1) es una propiedad de cadena que contiene la información sobre el vector de inicialización, la versión y la clave encapsulada.The first reserved property (_ClientEncryptionMetadata1) is a string property that holds the information about IV, version, and wrapped key. La segunda propiedad reservada (_ClientEncryptionMetadata2) es una propiedad binaria que contiene la información sobre las propiedades que se cifran.The second reserved property (_ClientEncryptionMetadata2) is a binary property that holds the information about the properties that are encrypted. La información de esta segunda propiedad (_ClientEncryptionMetadata2) está ella misma cifrada.The information in this second property (_ClientEncryptionMetadata2) is itself encrypted.
  4. A causa de estas propiedades reservadas adicionales necesarias para el cifrado, es posible que los usuarios ahora tengan solo 250 propiedades personalizadas en lugar de 252.Due to these additional reserved properties required for encryption, users may now have only 250 custom properties instead of 252. El tamaño total de la entidad debe ser inferior a 1 MB.The total size of the entity must be less than 1 MB.

Tenga en cuenta que solo se pueden cifrar las propiedades de cadena.Note that only string properties can be encrypted. Si hay que cifrar otros tipos de propiedades, habrá que convertirlas en cadenas.If other types of properties are to be encrypted, they must be converted to strings. Las cadenas cifradas se almacenan en el servicio como propiedades binarias y se convierten de nuevo en cadenas después del descifrado.The encrypted strings are stored on the service as binary properties, and they are converted back to strings after decryption.

Para las tablas, además de la directiva de cifrado, los usuarios deben especificar las propiedades que se van a cifrar.For tables, in addition to the encryption policy, users must specify the properties to be encrypted. Para ello, pueden especificar un atributo EncryptProperty (para las entidades POCO que se derivan de TableEntity) o una resolución de cifrado en las opciones de solicitud.This can be done by either specifying an [EncryptProperty] attribute (for POCO entities that derive from TableEntity) or an encryption resolver in request options. Una resolución de cifrado es un delegado que toma una clave de partición, una clave de fila y un nombre de propiedad y devuelve un valor booleano que indica si se debe cifrar dicha propiedad.An encryption resolver is a delegate that takes a partition key, row key, and property name and returns a Boolean that indicates whether that property should be encrypted. Durante el cifrado, la biblioteca de cliente usará esta información para decidir si se debe cifrar una propiedad mientras se escribe en la conexión.During encryption, the client library will use this information to decide whether a property should be encrypted while writing to the wire. El delegado también proporciona la posibilidad de lógica con respecto a la forma de cifrar las propiedades.The delegate also provides for the possibility of logic around how properties are encrypted. (Por ejemplo, si el valor es X, hay que cifrar la propiedad A; en caso contrario, hay que cifrar las propiedades A y B). Tenga en cuenta que no es necesario proporcionar esta información para leer o consultar entidades.(For example, if X, then encrypt property A; otherwise encrypt properties A and B.) Note that it is not necessary to provide this information while reading or querying entities.

Operaciones por lotesBatch Operations

En las operaciones por lotes, se usará la misma KEK en todas las filas de esa operación por lotes porque la biblioteca de cliente solo permite un objeto de opciones (y, por lo tanto, una directiva/KEK) por cada operación por lotes.In batch operations, the same KEK will be used across all the rows in that batch operation because the client library only allows one options object (and hence one policy/KEK) per batch operation. Sin embargo, la biblioteca de cliente generará internamente un nuevo vector de inicialización aleatorio y una CEK aleatoria por cada fila del lote.However, the client library will internally generate a new random IV and random CEK per row in the batch. Los usuarios también pueden optar por cifrar diferentes propiedades para cada operación del lote mediante la definición de este comportamiento en la resolución de cifrado.Users can also choose to encrypt different properties for every operation in the batch by defining this behavior in the encryption resolver.

ConsultasQueries

Nota

Dado que las entidades están cifradas, no se pueden ejecutar consultas que filtran por una propiedad cifrada.Because the entities are encrypted, you cannot run queries that filter on an encrypted property. Si lo intenta, los resultados serán incorrectos, porque el servicio estaría intentando comparar los datos cifrados con los datos sin cifrar.If you try, results will be incorrect, because the service would be trying to compare encrypted data with unencrypted data.

Para realizar operaciones de consulta, debe especificar a una resolución de clave que sea capaz de resolver todas las claves en el conjunto de resultados.To perform query operations, you must specify a key resolver that is able to resolve all the keys in the result set. Si una entidad incluida en el resultado de la consulta no se puede resolver en un proveedor, la biblioteca de cliente producirá un error.If an entity contained in the query result cannot be resolved to a provider, the client library will throw an error. Para cualquier consulta que realice proyecciones del lado servidor, la biblioteca de cliente agregará las propiedades de metadatos de cifrado especiales (_ClientEncryptionMetadata1 y _ClientEncryptionMetadata2) a las columnas seleccionadas de forma predeterminada.For any query that performs server-side projections, the client library will add the special encryption metadata properties (_ClientEncryptionMetadata1 and _ClientEncryptionMetadata2) by default to the selected columns.

Azure Key VaultAzure Key Vault

Azure Key Vault ayuda a proteger claves criptográficas y secretos usados por servicios y aplicaciones en la nube.Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Con Azure Key Vault, los usuarios pueden cifrar claves y secretos (por ejemplo, claves de autenticación, claves de cuenta de almacenamiento, claves de cifrado de datos, archivos .PFX y contraseñas) usando claves que están protegidas por módulos de seguridad de hardware (HSM).By using Azure Key Vault, users can encrypt keys and secrets (such as authentication keys, storage account keys, data encryption keys, .PFX files, and passwords) by using keys that are protected by hardware security modules (HSMs). Para obtener más información, consulte ¿Qué es Azure Key Vault?For more information, see What is Azure Key Vault?.

La biblioteca de cliente de almacenamiento utiliza la biblioteca básica de Key Vault para proporcionar un marco común en Azure para administrar las claves.The storage client library uses the Key Vault core library in order to provide a common framework across Azure for managing keys. Los usuarios obtienen también la ventaja adicional de usar la biblioteca de extensiones de Key Vault.Users also get the additional benefit of using the Key Vault extensions library. La biblioteca de extensiones ofrece funciones útiles para los proveedores de claves en la nube y locales simétricas/RSA, así como para la agregación y el almacenamiento en caché.The extensions library provides useful functionality around simple and seamless Symmetric/RSA local and cloud key providers as well as with aggregation and caching.

Interfaz y dependenciasInterface and dependencies

Hay tres paquetes de Key Vault:There are three Key Vault packages:

  • Microsoft.Azure.KeyVault.Core contiene IKey e IKeyResolver.Microsoft.Azure.KeyVault.Core contains the IKey and IKeyResolver. Es un paquete pequeño sin dependencias.It is a small package with no dependencies. La biblioteca de cliente de almacenamiento para .NET lo define como dependencia.The storage client library for .NET defines it as a dependency.
  • Microsoft.Azure.KeyVault contiene el cliente de REST de Key Vault.Microsoft.Azure.KeyVault contains the Key Vault REST client.
  • Microsoft.Azure.KeyVault.Extensions contiene el código de extensión que incluye implementaciones de algoritmos criptográficos, además de una RSAKey y una SymmetricKey.Microsoft.Azure.KeyVault.Extensions contains extension code that includes implementations of cryptographic algorithms and an RSAKey and a SymmetricKey. Depende de los espacios de nombres principales y KeyVault. Proporciona funcionalidad para definir una resolución de agregado (cuando los usuarios desean utilizar varios proveedores de clave) y una resolución de clave de almacenamiento en caché.It depends on the Core and KeyVault namespaces and provides functionality to define an aggregate resolver (when users want to use multiple key providers) and a caching key resolver. Aunque la biblioteca de cliente de almacenamiento no depende directamente de este paquete, si los usuarios desean usar Azure Key Vault para almacenar sus claves o utilizar las extensiones de Key Vault para consumir los proveedores de servicios criptográficos locales y en la nube, necesitarán este paquete.Although the storage client library does not directly depend on this package, if users wish to use Azure Key Vault to store their keys or to use the Key Vault extensions to consume the local and cloud cryptographic providers, they will need this package.

Key Vault está diseñado para claves maestras de gran valor. Por su parte, los valores de limitación por cada almacén de claves se diseñan teniendo en cuenta este aspecto.Key Vault is designed for high-value master keys, and throttling limits per Key Vault are designed with this in mind. Al realizar el cifrado en el lado cliente con Key Vault, el modelo preferido es usar las claves maestras simétricas almacenadas como secretos en Key Vault y almacenadas en caché localmente.When performing client-side encryption with Key Vault, the preferred model is to use symmetric master keys stored as secrets in Key Vault and cached locally. Los usuarios deben hacer lo siguiente:Users must do the following:

  1. Crear un secreto sin conexión y cargarlo en Key Vault.Create a secret offline and upload it to Key Vault.
  2. Usar el identificador de base del secreto como un parámetro para resolver la versión actual del secreto para el cifrado y el almacenamiento en caché de esta información localmente.Use the secret's base identifier as a parameter to resolve the current version of the secret for encryption and cache this information locally. Usar CachingKeyResolver para el almacenamiento en caché (los usuarios no deben implementar su propia lógica de almacenamiento en caché).Use CachingKeyResolver for caching; users are not expected to implement their own caching logic.
  3. Utilizar la resolución de caché como una entrada al crear la directiva de cifrado.Use the caching resolver as an input while creating the encryption policy.

Puede encontrar más información acerca del uso de Key Vault en los ejemplos de código de cifrado.More information regarding Key Vault usage can be found in the encryption code samples.

Procedimientos recomendadosBest practices

La compatibilidad con el cifrado solo está disponible en la biblioteca de cliente de almacenamiento para .NET.Encryption support is available only in the storage client library for .NET. Windows Phone y Windows en tiempo de ejecución no admiten actualmente cifrado.Windows Phone and Windows Runtime do not currently support encryption.

Importante

Tenga en cuenta estos puntos importantes al usar el cifrado del lado del cliente:Be aware of these important points when using client-side encryption:

  • Al leer desde un blob cifrado o escribir en él, utilice comandos de carga completa del blob y comandos de descarga de blobs de intervalo/completos.When reading from or writing to an encrypted blob, use whole blob upload commands and range/whole blob download commands. Evite escribir en un blob cifrado mediante operaciones de protocolo, como Colocar bloque, Colocar lista de bloque, Escribir páginas, Borrar páginas o Anexar bloque; de lo contrario, puede dañar el objeto blob cifrado y que no sea legible.Avoid writing to an encrypted blob using protocol operations such as Put Block, Put Block List, Write Pages, Clear Pages, or Append Block; otherwise you may corrupt the encrypted blob and make it unreadable.
  • Para las tablas, existe una restricción similar.For tables, a similar constraint exists. Tenga cuidado de no actualizar propiedades cifradas sin actualizar los metadatos de cifrado.Be careful to not update encrypted properties without updating the encryption metadata.
  • Si establece los metadatos en el objeto blob cifrado, puede sobrescribir los metadatos relacionados con el cifrado necesarios para el descifrado, ya que el establecimiento de metadatos no es aditivo.If you set metadata on the encrypted blob, you may overwrite the encryption-related metadata required for decryption, since setting metadata is not additive. Esto también se aplica a las instantáneas: evite la especificación de metadatos durante la creación de una instantánea de un blob cifrado.This is also true for snapshots; avoid specifying metadata while creating a snapshot of an encrypted blob. Si se deben establecer metadatos, asegúrese de llamar primero al método FetchAttributes , para así obtener los metadatos de cifrado actuales y evitar las escrituras simultáneas mientras se estos se establecen.If metadata must be set, be sure to call the FetchAttributes method first to get the current encryption metadata, and avoid concurrent writes while metadata is being set.
  • Habilite la propiedad RequireEncryption en las opciones de solicitud predeterminadas para los usuarios que deben trabajar solo con datos cifrados.Enable the RequireEncryption property in the default request options for users that should work only with encrypted data. Vea a continuación para obtener más información.See below for more info.

Interfaz/API de clienteClient API / Interface

Al crear un objeto de EncryptionPolicy, los usuarios pueden proporcionar solo una clave (implementación de IKey), solo una resolución (implementación de IKeyResolver) o ambas.While creating an EncryptionPolicy object, users can provide only a Key (implementing IKey), only a resolver (implementing IKeyResolver), or both. IKey es el tipo de clave básico que se identifica mediante un identificador de claves y que proporciona la lógica para la encapsulación y desencapsulación.IKey is the basic key type that is identified using a key identifier and that provides the logic for wrapping/unwrapping. IKeyResolver se utiliza para resolver una clave durante el proceso de descifrado.IKeyResolver is used to resolve a key during the decryption process. Define un método ResolveKey que devuelve un IKey concreto (identificador de clave).It defines a ResolveKey method that returns an IKey given a key identifier. Esto ofrece a los usuarios la posibilidad de elegir entre varias claves que se administran en varias ubicaciones.This provides users the ability to choose between multiple keys that are managed in multiple locations.

  • Para el cifrado, se utiliza siempre la clave. Si no hay clave, se producirá un error.For encryption, the key is used always and the absence of a key will result in an error.
  • Para el descifrado:For decryption:
    • La resolución de claves se invoca si se especifica para obtener la clave.The key resolver is invoked if specified to get the key. Si se especifica la resolución, pero no se proporciona una asignación para el identificador de clave, se produce un error.If the resolver is specified but does not have a mapping for the key identifier, an error is thrown.
    • Si no se especifica la resolución, pero sí se especifica una clave, la clave se usa si su identificador coincide con el identificador de clave necesario.If resolver is not specified but a key is specified, the key is used if its identifier matches the required key identifier. Si el identificador no coincide, se genera un error.If the identifier does not match, an error is thrown.

Los ejemplos de código en este artículo muestran el establecimiento de una directiva de cifrado y el funcionamiento con datos cifrados, pero no muestran el funcionamiento con Azure Key Vault.The code examples in this article demonstrate setting an encryption policy and working with encrypted data, but do not demonstrate working with Azure Key Vault. Los ejemplos de cifrado en GitHub muestran un escenario más detallado de un extremo a otro para blobs, colas y tablas, junto con la integración del Almacén de claves.The encryption samples on GitHub demonstrate a more detailed end-to-end scenario for blobs, queues and tables, along with Key Vault integration.

Modo RequireEncryptionRequireEncryption mode

Los usuarios pueden habilitar opcionalmente un modo de operación en el que se deben cifrar todas las cargas y descargas.Users can optionally enable a mode of operation where all uploads and downloads must be encrypted. En este modo, los intentos de cargar datos sin una directiva de cifrado o de descargar datos no cifrados en el servicio generarán un error en el cliente.In this mode, attempts to upload data without an encryption policy or download data that is not encrypted on the service will fail on the client. Este comportamiento lo controla la propiedad RequireEncryption de los controles de objeto de las opciones de solicitud.The RequireEncryption property of the request options object controls this behavior. Si la aplicación va a cifrar todos los objetos almacenados en Azure Storage, puede establecer la propiedad RequireEncryption en las opciones de solicitud predeterminadas del objeto de cliente de servicio.If your application will encrypt all objects stored in Azure Storage, then you can set the RequireEncryption property on the default request options for the service client object. Por ejemplo, establezca CloudBlobClient.DefaultRequestOptions.RequireEncryption en true para requerir que se realice el cifrado para todas las operaciones de blobs realizadas a través de ese objeto de cliente.For example, set CloudBlobClient.DefaultRequestOptions.RequireEncryption to true to require encryption for all blob operations performed through that client object.

Cifrado de Blob serviceBlob service encryption

Cree un objeto BlobEncryptionPolicy y configúrelo en las opciones de solicitud (por API o en un nivel de cliente mediante el elemento DefaultRequestOptions).Create a BlobEncryptionPolicy object and set it in the request options (per API or at a client level by using DefaultRequestOptions). Todo lo demás lo controlará la biblioteca de cliente internamente.Everything else will be handled by the client library internally.

// Create the IKey used for encryption.
 RsaKey key = new RsaKey("private:key1" /* key identifier */);

 // Create the encryption policy to be used for upload and download.
 BlobEncryptionPolicy policy = new BlobEncryptionPolicy(key, null);

 // Set the encryption policy on the request options.
 BlobRequestOptions options = new BlobRequestOptions() { EncryptionPolicy = policy };

 // Upload the encrypted contents to the blob.
 blob.UploadFromStream(stream, size, null, options, null);

 // Download and decrypt the encrypted contents from the blob.
 MemoryStream outputStream = new MemoryStream();
 blob.DownloadToStream(outputStream, null, options, null);

Cifrado del servicio ColaQueue service encryption

Cree un objeto QueueEncryptionPolicy y configúrelo en las opciones de solicitud (por API o en el nivel del cliente usando DefaultRequestOptions).Create a QueueEncryptionPolicy object and set it in the request options (per API or at a client level by using DefaultRequestOptions). Todo lo demás lo controlará la biblioteca de cliente internamente.Everything else will be handled by the client library internally.

// Create the IKey used for encryption.
 RsaKey key = new RsaKey("private:key1" /* key identifier */);

 // Create the encryption policy to be used for upload and download.
 QueueEncryptionPolicy policy = new QueueEncryptionPolicy(key, null);

 // Add message
 QueueRequestOptions options = new QueueRequestOptions() { EncryptionPolicy = policy };
 queue.AddMessage(message, null, null, options, null);

 // Retrieve message
 CloudQueueMessage retrMessage = queue.GetMessage(null, options, null);

Cifrado de Table serviceTable service encryption

Además de crear una directiva de cifrado y configurarla en las opciones de solicitud, debe especificar un elemento EncryptionResolver en TableRequestOptions o establecer el atributo [EncryptProperty] en la entidad.In addition to creating an encryption policy and setting it on request options, you must either specify an EncryptionResolver in TableRequestOptions, or set the [EncryptProperty] attribute on the entity.

Uso de la resoluciónUsing the resolver

// Create the IKey used for encryption.
 RsaKey key = new RsaKey("private:key1" /* key identifier */);

 // Create the encryption policy to be used for upload and download.
 TableEncryptionPolicy policy = new TableEncryptionPolicy(key, null);

 TableRequestOptions options = new TableRequestOptions()
 {
    EncryptionResolver = (pk, rk, propName) =>
     {
        if (propName == "foo")
         {
            return true;
         }
         return false;
     },
     EncryptionPolicy = policy
 };

 // Insert Entity
 currentTable.Execute(TableOperation.Insert(ent), options, null);

 // Retrieve Entity
 // No need to specify an encryption resolver for retrieve
 TableRequestOptions retrieveOptions = new TableRequestOptions()
 {
    EncryptionPolicy = policy
 };

 TableOperation operation = TableOperation.Retrieve(ent.PartitionKey, ent.RowKey);
 TableResult result = currentTable.Execute(operation, retrieveOptions, null);

Uso de los atributosUsing attributes

Tal como se mencionó anteriormente, si la entidad implementa TableEntity, las propiedades se pueden completar con el atributo [EncryptProperty] en lugar de especificar EncryptionResolver.As mentioned above, if the entity implements TableEntity, then the properties can be decorated with the [EncryptProperty] attribute instead of specifying the EncryptionResolver.

[EncryptProperty]
 public string EncryptedProperty1 { get; set; }

Cifrado y rendimientoEncryption and performance

Tenga en cuenta que el cifrado de sus resultados de datos de almacenamiento da lugar a la sobrecarga de rendimiento adicional.Note that encrypting your storage data results in additional performance overhead. Se deben generar la clave de contenido e IV, se debe cifrar el propio contenido y se deben formatear y cargar metadatos adicionales.The content key and IV must be generated, the content itself must be encrypted, and additional meta-data must be formatted and uploaded. Esta sobrecarga variará según la cantidad de datos que se cifran.This overhead will vary depending on the quantity of data being encrypted. Se recomienda que los clientes prueben siempre sus aplicaciones para obtener un rendimiento durante el desarrollo.We recommend that customers always test their applications for performance during development.

Pasos siguientesNext steps