Biblioteca cliente de criptografía de Blobs de Azure Storage para Java: versión 12.23.1

  • Artículo

Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube. El almacenamiento de blobs está optimizado para almacenar grandes cantidades de datos no estructurados. Los datos no estructurados son datos que no cumplen un modelo de datos o definición concreta, como texto o datos binarios. Este paquete admite el cifrado del lado cliente para Blob Storage.

Código | fuenteDocumentación | de referencia de APIDocumentación | de la API RESTDocumentación | del productoMuestras

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, luego, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob-cryptography</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob-cryptography</artifactId>
  <version>12.23.1</version>
</dependency>

Creación de una cuenta de almacenamiento

Para crear una cuenta de almacenamiento, puede usar Azure Portal o la CLI de Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Autenticar el cliente

Para interactuar con el servicio Storage (Blob, Queue, Message, MessageId, File), deberá crear una instancia de la clase Service Client. Para que esto sea posible, necesitará la cadena saS de cuenta (firma de acceso compartido) de la cuenta de almacenamiento. Más información en Token de SAS

Obtener credenciales

  • SAS Token

a. Use el fragmento de código de la CLI de Azure siguiente para obtener el token de SAS de la cuenta de almacenamiento.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Ejemplo:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Como alternativa, obtenga el token de SAS de cuenta de Azure Portal.

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Shared access signature en el menú de la izquierda.
  3. Haga clic en Generate SAS and connection string (después de la configuración)
Credencial de clave compartida

a. Use Nombre de cuenta y Clave de cuenta. El nombre de la cuenta es el nombre de la cuenta de almacenamiento.

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Access keys en el menú de la izquierda.
  3. En key1/key2 copiar el contenido del Key campo

o

b. Use el cadena de conexión.

  1. Vaya a la cuenta de almacenamiento.
  2. Seleccione Access keys en el menú de la izquierda.
  3. En key1/key2 copiar el contenido del Connection string campo

Conceptos clave

Blob Storage está diseñado para:

  • Visualización de imágenes o documentos directamente en un explorador.
  • Almacenamiento de archivos para acceso distribuido.
  • Streaming de audio y vídeo.
  • Escribir en archivos de registro.
  • Almacenamiento de datos para copia de seguridad y restauración, recuperación ante desastres y archivado.
  • Almacenamiento de datos para el análisis en local o en un servicio hospedado de Azure.

Ejemplos

Nota: El uso de EncryptedBlobClient es el mismo que el equivalente BlobClient, la única diferencia es la construcción del cliente. Consulte para conocer azure-storage-blob los casos de uso comunes de BlobClient

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas de creación de criptografía de blobs de Azure Storage más comunes, entre las que se incluyen:

Creación de un objeto EncryptedBlobClient a partir de BlobClient

Cree un EncryptedBlobClient objeto mediante .BlobClient BlobClient la construcción se explica en el azure-storage-blob ARCHIVO LÉAME.

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .blobClient(blobClient)
    .buildEncryptedBlobClient();

Cree una clave privada RSA EncryptedBlobClient.

Cree un BlobServiceClient mediante un cadena de conexión.

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(key, keyWrapAlgorithm)
    .keyResolver(keyResolver)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Uso de un local KeyEncryptionKey

JsonWebKey localKey = JsonWebKey.fromAes(new SecretKeySpec(keyBytes, secretKeyAlgorithm),
    Arrays.asList(KeyOperation.WRAP_KEY, KeyOperation.UNWRAP_KEY))
    .setId("my-id");
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .buildAsyncKeyEncryptionKey(localKey).block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Usar una KeyVaultKey

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl(keyVaultUrl)
    .credential(tokenCredential)
    .buildClient();
KeyVaultKey rsaKey = keyClient.createRsaKey(new CreateRsaKeyOptions(keyName)
    .setExpiresOn(OffsetDateTime.now().plusYears(1))
    .setKeySize(2048));
AsyncKeyEncryptionKey akek = new KeyEncryptionKeyClientBuilder()
    .credential(tokenCredential)
    .buildAsyncKeyEncryptionKey(rsaKey.getId())
    .block();

EncryptedBlobClient client = new EncryptedBlobClientBuilder()
    .key(akek, keyWrapAlgorithm)
    .connectionString(connectionString)
    .containerName(containerName)
    .blobName(blobName)
    .buildEncryptedBlobClient();

Solución de problemas

Al interactuar con blobs mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de LA API REST . Por ejemplo, si intenta recuperar un contenedor o un blob que no existe en la cuenta de almacenamiento, se devuelve un 404 error, que indica Not Found.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Biblioteca SSL predeterminada

De forma predeterminada, todas las bibliotecas cliente usan la biblioteca Boring SSL nativa de Tomcat para habilitar el rendimiento de nivel nativo para las operaciones SSL. La biblioteca Boring SSL es un archivo uber-jar que contiene bibliotecas nativas para Linux, macOS o Windows, que proporciona un mejor rendimiento en comparación con la implementación SSL predeterminada del JDK. Para obtener más información, incluido cómo reducir el tamaño de las dependencias, consulte la sección optimización del rendimiento de la wiki.

Pasos siguientes

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones