Utilizzo della libreria di crittografia lato client Java per DynamoDB

La nostra libreria di crittografia lato client è stata rinominata Database Encryption SDK. AWS Questa guida per sviluppatori fornisce ancora informazioni sul DynamoDB Encryption Client.

Questo argomento spiega alcune delle funzioni e delle classi di supporto della versione 3. x della libreria di crittografia lato client Java per DynamoDB.

Per i dettagli sulla programmazione con la libreria di crittografia lato client Java per DynamoDB, consulta gli esempi Java, gli esempi Java nel repository -dynamodb su. aws-database-encryption-sdk GitHub

Componenti di crittografia dell'item

Fondamentalmente, il AWS Database Encryption SDK per DynamoDB è un cifratore di elementi. È possibile utilizzare la versione 3. x della libreria di crittografia lato client Java per DynamoDB per crittografare, firmare, verificare e decrittografare gli elementi della tabella DynamoDB nei seguenti modi.

Il client avanzato per DynamoDB

È possibile configurare il DynamoDB Enhanced Client per crittografare e firmare automaticamente DynamoDbEncryptionInterceptor gli elementi lato client con le richieste DynamoDB. PutItem Con DynamoDB Enhanced Client, puoi definire le azioni degli attributi utilizzando una classe di dati annotata. Consigliamo di utilizzare il DynamoDB Enhanced Client ogni volta che è possibile.

Il DynamoDB Enhanced Client non supporta la crittografia ricercabile.

Nota

Il AWS Database Encryption SDK non supporta le annotazioni sugli attributi annidati.

L'API DynamoDB di basso livello

Puoi configurare l'API DynamoDB di basso livello per crittografare e firmare automaticamente gli elementi lato client con DynamoDbEncryptionInterceptor le tue richieste DynamoDB. PutItem

È necessario utilizzare l'API DynamoDB di basso livello per utilizzare la crittografia ricercabile.

Il livello inferiore DynamoDbItemEncryptor

Il livello inferiore crittografa e firma o decrittografa e verifica DynamoDbItemEncryptor direttamente gli elementi della tabella senza chiamare DynamoDB. Non crea DynamoDB o PutItem richiesteGetItem. Ad esempio, puoi utilizzare il livello inferiore per DynamoDbItemEncryptor decrittografare e verificare direttamente un elemento DynamoDB che hai già recuperato.

Il livello inferiore non supporta la crittografia ricercabile. DynamoDbItemEncryptor

Azioni relative agli attributi nel AWS Database Encryption SDK per DynamoDB

Le azioni relative agli attributi determinano quali valori degli attributi sono crittografati e firmati, quali sono solo firmati, quali sono firmati e inclusi nel contesto di crittografia e quali vengono ignorati.

Nota

Per utilizzare l'azione SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT crittografica, è necessario utilizzare la versione 3.3 o successiva di AWS Database Encryption SDK. Distribuisci la nuova versione a tutti i lettori prima di aggiornare il modello di dati per includere. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT

Se utilizzi l'API DynamoDB di basso livello o il DynamoDbItemEncryptor livello inferiore, devi definire manualmente le azioni degli attributi. Se si utilizza il DynamoDB Enhanced Client, è possibile definire manualmente le azioni relative agli attributi oppure utilizzare una classe di dati annotata per generare un. TableSchema Per semplificare il processo di configurazione, consigliamo di utilizzare una classe di dati annotata. Quando utilizzate una classe di dati annotata, dovete modellare l'oggetto una sola volta.

Nota

Dopo aver definito le azioni relative agli attributi, è necessario definire quali attributi sono esclusi dalle firme. Per semplificare l'aggiunta di nuovi attributi non firmati in futuro, consigliamo di scegliere un prefisso distinto (ad esempio ":«) per identificare gli attributi non firmati. Includi questo prefisso nel nome dell'attributo per tutti gli attributi contrassegnati durante DO_NOTHING la definizione dello schema DynamoDB e delle azioni degli attributi.

Utilizza una classe di dati annotata

Utilizza una classe di dati annotata per specificare le azioni degli attributi con DynamoDB Enhanced Client e. DynamoDbEncryptionInterceptor Il AWS Database Encryption SDK per DynamoDB utilizza le annotazioni standard degli attributi DynamoDB che definiscono il tipo di attributo per determinare come proteggere un attributo. Per impostazione predefinita, tutti gli attributi sono crittografati e firmati, tranne le chiavi primarie, che sono firmate ma non crittografate.

Nota

Per utilizzare l'azione SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT crittografica, è necessario utilizzare la versione 3.3 o successiva del Database Encryption SDK. AWS Distribuisci la nuova versione a tutti i lettori prima di aggiornare il modello di dati per includere. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT

SimpleClassConsulta.java nel repository aws-database-encryption-sdk -dynamodb su GitHub per ulteriori indicazioni sulle annotazioni di DynamoDB Enhanced Client.

Per impostazione predefinita, gli attributi della chiave primaria sono firmati ma non crittografati (SIGN_ONLY) e tutti gli altri attributi sono crittografati e firmati (). ENCRYPT_AND_SIGN Se si definiscono gli attributi comeSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, allora anche gli attributi di partizione e ordinamento devono esserloSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Per specificare le eccezioni, utilizzate le annotazioni di crittografia definite nella libreria di crittografia lato client Java per DynamoDB. Ad esempio, se desideri che un particolare attributo venga firmato, utilizza l'annotazione. @DynamoDbEncryptionSignOnly Se desideri che un particolare attributo venga firmato e incluso nel contesto di crittografia, usa il@DynamoDbEncryptionSignAndIncludeInEncryptionContext. Se vuoi che un particolare attributo non sia né firmato né crittografato (DO_NOTHING), usa l'@DynamoDbEncryptionDoNothingannotazione.

Nota

Il AWS Database Encryption SDK non supporta le annotazioni sugli attributi annidati.

L'esempio seguente mostra le annotazioni utilizzate per definire e attribuire ENCRYPT_AND_SIGN le SIGN_ONLY azioni. DO_NOTHING Per un esempio che mostra le annotazioni utilizzate per definireSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, vedete SimpleClass 4.java.

@DynamoDbBean
public class SimpleClass {

    private String partitionKey;
    private int sortKey;
    private String attribute1;
    private String attribute2;
    private String attribute3;

    @DynamoDbPartitionKey
    @DynamoDbAttribute(value = "partition_key")
    public String getPartitionKey() {
        return this.partitionKey;
    }

    public void setPartitionKey(String partitionKey) {
        this.partitionKey = partitionKey;
    }

    @DynamoDbSortKey
    @DynamoDbAttribute(value = "sort_key")
    public int getSortKey() {
        return this.sortKey;
    }

    public void setSortKey(int sortKey) {
        this.sortKey = sortKey;
    }

    public String getAttribute1() {
        return this.attribute1;
    }

    public void setAttribute1(String attribute1) {
        this.attribute1 = attribute1;
    }

    @DynamoDbEncryptionSignOnly
    public String getAttribute2() {
        return this.attribute2;
    }

    public void setAttribute2(String attribute2) {
        this.attribute2 = attribute2;
    }

    @DynamoDbEncryptionDoNothing
    public String getAttribute3() {
        return this.attribute3;
    }

    @DynamoDbAttribute(value = ":attribute3")
    public void setAttribute3(String attribute3) {
        this.attribute3 = attribute3;
    }
    
}

Mostra piùMostra meno

Usa la tua classe di dati annotata per creare il file TableSchema come mostrato nel seguente frammento.

final TableSchema<SimpleClass> tableSchema = TableSchema.fromBean(SimpleClass.class);

Definisci manualmente le azioni degli attributi

Per specificare manualmente le azioni degli attributi, create un Map oggetto in cui le coppie nome-valore rappresentino i nomi degli attributi e le azioni specificate.

Specificate ENCRYPT_AND_SIGN di crittografare e firmare un attributo. SIGN_ONLYSpecificare di firmare, ma non crittografare, un attributo. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXTSpecificare di firmare un attributo e di includerlo nel contesto di crittografia. Non è possibile crittografare un attributo senza firmarlo. DO_NOTHINGSpecificare di ignorare un attributo.

Gli attributi di partizione e ordinamento devono essere SIGN_ONLY oSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Se si definiscono gli attributi comeSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, allora anche gli attributi di partizione e ordinamento devono essere uguali. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT

Nota

Per utilizzare l'azione SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT crittografica, è necessario utilizzare la versione 3.3 o successiva del AWS Database Encryption SDK. Distribuisci la nuova versione a tutti i lettori prima di aggiornare il modello di dati per includere. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT

final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be signed
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT); 
// The sort attribute must be signed
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put("attribute3", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT);
attributeActionsOnEncrypt.put(":attribute4", CryptoAction.DO_NOTHING);

Configurazione della crittografia nel AWS Database Encryption SDK per DynamoDB

Quando si utilizza AWS Database Encryption SDK, è necessario definire in modo esplicito una configurazione di crittografia per la tabella DynamoDB. I valori richiesti nella configurazione di crittografia dipendono dal fatto che le azioni degli attributi siano state definite manualmente o con una classe di dati annotata.

Il seguente frammento definisce una configurazione di crittografia delle tabelle DynamoDB utilizzando il DynamoDB Enhanced Client e gli attributi non firmati consentiti definiti da un prefisso TableSchemadistinto.

final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
        DynamoDbEnhancedTableEncryptionConfig.builder()
            .logicalTableName(ddbTableName)
            .keyring(kmsKeyring)
            .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
            .schemaOnEncrypt(tableSchema)
            // Optional: only required if you use beacons
            .search(SearchConfig.builder() 
                    .writeVersion(1) // MUST be 1
                    .versions(beaconVersions)
                    .build())         
            .build());

Nome della tabella logica

Un nome di tabella logica per la tabella DynamoDB.

Il nome della tabella logica è associato crittograficamente a tutti i dati memorizzati nella tabella per semplificare le operazioni di ripristino di DynamoDB. Consigliamo vivamente di specificare il nome della tabella DynamoDB come nome della tabella logica quando si definisce per la prima volta la configurazione di crittografia. È necessario specificare sempre lo stesso nome di tabella logica. Affinché la decrittografia abbia esito positivo, il nome della tabella logica deve corrispondere al nome specificato nella crittografia. Nel caso in cui il nome della tabella DynamoDB cambi dopo il ripristino della tabella DynamoDB da un backup, il nome della tabella logica assicura che l'operazione di decrittografia riconosca ancora la tabella.

Attributi non firmati consentiti

Gli attributi contrassegnati DO_NOTHING nelle azioni relative agli attributi.

Gli attributi non firmati consentiti indicano al client quali attributi sono esclusi dalle firme. Il client presume che tutti gli altri attributi siano inclusi nella firma. Quindi, durante la decrittografia di un record, il client determina quali attributi deve verificare e quali ignorare tra gli attributi non firmati consentiti specificati. Non è possibile rimuovere un attributo dagli attributi non firmati consentiti.

È possibile definire gli attributi non firmati consentiti in modo esplicito creando un array che elenca tutti gli attributi. DO_NOTHING È inoltre possibile specificare un prefisso distinto quando si assegnano nomi DO_NOTHING agli attributi e utilizzare il prefisso per indicare al client quali attributi non sono firmati. Consigliamo vivamente di specificare un prefisso distinto perché semplifica il processo di aggiunta di un nuovo DO_NOTHING attributo in futuro. Per ulteriori informazioni, consulta Aggiornamento del modello di dati.

Se non si specifica un prefisso per tutti gli DO_NOTHING attributi, è possibile configurare un allowedUnsignedAttributes array che elenchi in modo esplicito tutti gli attributi che il client dovrebbe aspettarsi che non siano firmati quando li incontra durante la decrittografia. È necessario definire in modo esplicito gli attributi non firmati consentiti solo se assolutamente necessario.

Configurazione della ricerca (opzionale)

SearchConfigdefinisce la versione del beacon.

È SearchConfig necessario specificare il per utilizzare la crittografia ricercabile o i beacon firmati.

Algorithm Suite (opzionale)

algorithmSuiteIdDefinisce la suite di algoritmi utilizzata da AWS Database Encryption SDK.

A meno che non si specifichi esplicitamente una suite di algoritmi alternativa, AWS Database Encryption SDK utilizza la suite di algoritmi predefinita. La suite di algoritmi predefinita utilizza l'algoritmo AES-GCM con derivazione delle chiavi, firme digitali e impegno delle chiavi. Sebbene la suite di algoritmi predefinita sia probabilmente adatta alla maggior parte delle applicazioni, è possibile scegliere una suite di algoritmi alternativa. Ad esempio, alcuni modelli di fiducia sarebbero soddisfatti da una suite di algoritmi senza firme digitali. Per informazioni sulle suite di algoritmi supportate da AWS Database Encryption SDK, consulta. Suite di algoritmi supportate nel AWS Database Encryption SDK

Per selezionare la suite di algoritmi AES-GCM senza firme digitali ECDSA, includi il seguente frammento nella configurazione di crittografia delle tabelle.

.algorithmSuiteId(
    DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)

Aggiornamento degli AWS elementi con Database Encryption SDK

Il AWS Database Encryption SDK non supporta ddb: UpdateItem per gli elementi che sono stati crittografati o firmati. Per aggiornare un elemento crittografato o firmato, è necessario utilizzare ddb:. PutItem Quando specifichi la stessa chiave primaria di un elemento esistente nella tua PutItem richiesta, il nuovo elemento sostituisce completamente l'elemento esistente. Puoi anche usare CLOBBER per cancellare e sostituire tutti gli attributi al momento del salvataggio dopo aver aggiornato i tuoi articoli.

Decrittografia dei set firmati

Nelle versioni 3.0.0 e 3.1.0 di AWS Database Encryption SDK, se si definisce un attributo di tipo set comeSIGN_ONLY, i valori del set vengono canonicalizzati nell'ordine in cui vengono forniti. DynamoDB non mantiene l'ordine dei set. Di conseguenza, c'è la possibilità che la convalida della firma dell'elemento che contiene il set abbia esito negativo. La convalida della firma ha esito negativo quando i valori del set vengono restituiti in un ordine diverso da quello fornito al AWS Database Encryption SDK, anche se gli attributi del set contengono gli stessi valori.

Nota

Le versioni 3.1.1 e successive del AWS Database Encryption SDK canonicalizzano i valori di tutti gli attributi dei tipi di set, in modo che i valori vengano letti nello stesso ordine in cui sono stati scritti in DynamoDB.

Se la convalida della firma fallisce, l'operazione di decrittografia fallisce e restituisce il seguente messaggio di errore.

software.amazon.cryptography.dbencryptionsdk.structuredencryption.model. StructuredEncryptionException: Nessun tag del destinatario corrispondente.

Se ricevete il messaggio di errore riportato sopra e ritenete che l'elemento che state cercando di decrittografare includa un set firmato utilizzando la versione 3.0.0 o 3.1.0, consultate la DecryptWithPermutedirectory del repository aws-database-encryption-sdk -dynamodb-java su per i dettagli su come convalidare correttamente il set. GitHub