SDK di crittografia AWS per JavaScript esempi - AWS Encryption SDK
AWS KMS Crittografia dei dati con un portachiaviDecrittografia dei dati con un portachiavi AWS KMS

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

SDK di crittografia AWS per JavaScript esempi

Gli esempi seguenti illustrano come utilizzare SDK di crittografia AWS per JavaScript per crittografare e decrittare i dati.

Puoi trovare altri esempi di utilizzo dei moduli example-node ed example-browser SDK di crittografia AWS per JavaScript nel repository su. aws-encryption-sdk-javascript GitHub Questi moduli di esempio non vengono installati quando installi i moduli client-browser o client-node.

Vedi gli esempi di codice completi: Nodo: kms_simple.ts, Browser: kms_simple.ts

AWS KMS Crittografia dei dati con un portachiavi

L'esempio seguente mostra come utilizzare per crittografare e SDK di crittografia AWS per JavaScript decrittografare una stringa breve o un array di byte.

Questo esempio presenta un AWS KMS portachiavi, un tipo di portachiavi che utilizza un AWS KMS key per generare e crittografare chiavi di dati. Per informazioni sulla creazione di un AWS KMS key, consulta Creating Keys nella Developer Guide.AWS Key Management Service Per informazioni su come identificarle AWS KMS keys in un AWS KMS portachiavi, consulta Identificazione AWS KMS keys in un portachiavi AWS KMS

Fase 1: Impostare la politica di impegno.

A partire dalla versione 1.7. x of the SDK di crittografia AWS per JavaScript, è possibile impostare la politica di impegno quando si chiama la nuova buildClient funzione che crea un'istanza di un AWS Encryption SDK client. La buildClient funzione assume un valore enumerato che rappresenta la politica di impegno dell'utente. Restituisce decrypt funzioni aggiornate encrypt e che applicano la politica di impegno dell'utente durante la crittografia e la decrittografia.

Gli esempi seguenti utilizzano la buildClient funzione per specificare la politica di impegno predefinita,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT È inoltre possibile utilizzare il buildClient per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta Limitazione delle chiavi di dati crittografate.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Fase 2: Costruisci il portachiavi.

Crea un AWS KMS portachiavi per la crittografia.

Quando si esegue la crittografia con un AWS KMS portachiavi, è necessario specificare una chiave generatrice, ovvero una AWS KMS key chiave utilizzata per generare la chiave di dati in testo semplice e crittografarla. Inoltre puoi specificare zero o più chiavi aggiuntive per crittografare la stessa chiave di dati di testo normale. Il portachiavi restituisce la chiave di dati in testo semplice e una copia crittografata di tale chiave dati per ogni AWS KMS key elemento del portachiavi, inclusa la chiave del generatore. Per decrittare i dati, è necessario decrittare una qualsiasi delle chiavi di dati crittografate.

Per specificare il AWS KMS keys portachiavi di crittografia in SDK di crittografia AWS per JavaScript, puoi utilizzare qualsiasi identificatore di chiave supportato. AWS KMS Questo esempio utilizza una chiave generatrice, identificata dal relativo alias ARN, e una chiave aggiuntiva, identificata da una chiave. ARN

Nota

Se si prevede di riutilizzare il AWS KMS portachiavi per la decrittografia, è necessario utilizzare la chiave per ARNs identificare il portachiavi. AWS KMS keys

Prima di eseguire questo codice, sostituite gli identificatori di esempio AWS KMS key con identificatori validi. Devi disporre delle autorizzazioni necessarie per utilizzare le AWS KMS keys nel keyring.

JavaScript Browser

Inizia fornendo le credenziali nel browser. Gli SDK di crittografia AWS per JavaScript esempi utilizzano il webpack. DefinePlugin, che sostituisce le costanti delle credenziali con le credenziali effettive. Tuttavia puoi utilizzare qualsiasi metodo per fornire le credenziali. Quindi, utilizza le credenziali per creare un client. AWS KMS 

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }

const clientProvider = getClient(KMS, {
  credentials: {
    accessKeyId,
    secretAccessKey,
    sessionToken
  }
})

Quindi, specifica AWS KMS keys la chiave del generatore e la chiave aggiuntiva. Quindi, crea un AWS KMS portachiavi utilizzando il AWS KMS client e il AWS KMS keys.

const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
JavaScript Node.js
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
Passaggio 3: Impostare il contesto di crittografia.

Un contesto di crittografia è rappresentato da tipi di dati autenticati aggiuntivi arbitrari e non segreti. Quando si fornisce un contesto di crittografia su encrypt, associa AWS Encryption SDK crittograficamente il contesto di crittografia al testo cifrato in modo che sia necessario lo stesso contesto di crittografia per decrittografare i dati. L'utilizzo di un contesto di crittografia è facoltativo, ma viene consigliato come best practice.

Crea un oggetto semplice che includa le coppie di contesto di crittografia. La chiave e il valore di ogni coppia devono essere una stringa.

JavaScript Browser
const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}
JavaScript Node.js
const context = {
  stage: 'demo',
  purpose: 'simple demonstration app',
  origin: 'us-west-2'
}
Fase 4: Crittografare i dati.

Per crittografare i dati di testo normale, chiama la funzione encrypt. Inserisci il AWS KMS portachiavi, i dati in chiaro e il contesto di crittografia.

La funzione encrypt restituisce un messaggio crittografato (result) che contiene i dati crittografati, le chiavi di dati crittografate e i metadati importanti, inclusi il contesto di crittografia e la firma.

È possibile decrittografare questo messaggio crittografato utilizzando il AWS Encryption SDK per qualsiasi linguaggio di programmazione supportato.

JavaScript Browser
const plaintext = new Uint8Array([1, 2, 3, 4, 5])

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
JavaScript Node.js
const plaintext = 'asdf'

const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })

Decrittografia dei dati con un portachiavi AWS KMS

È possibile utilizzare il SDK di crittografia AWS per JavaScript per decrittografare il messaggio crittografato e recuperare i dati originali.

In questo esempio, esegui la decrittazione dei dati crittografati nell'esempio AWS KMS Crittografia dei dati con un portachiavi.

Fase 1: Impostare la politica di impegno.

A partire dalla versione 1.7. x of the SDK di crittografia AWS per JavaScript, è possibile impostare la politica di impegno quando si chiama la nuova buildClient funzione che crea un'istanza di un AWS Encryption SDK client. La buildClient funzione assume un valore enumerato che rappresenta la politica di impegno dell'utente. Restituisce decrypt funzioni aggiornate encrypt e che applicano la politica di impegno dell'utente durante la crittografia e la decrittografia.

Gli esempi seguenti utilizzano la buildClient funzione per specificare la politica di impegno predefinita,. REQUIRE_ENCRYPT_REQUIRE_DECRYPT È inoltre possibile utilizzare il buildClient per limitare il numero di chiavi di dati crittografate in un messaggio crittografato. Per ulteriori informazioni, consulta Limitazione delle chiavi di dati crittografate.

JavaScript Browser
import {
  KmsKeyringBrowser,
  KMS,
  getClient,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-browser'

const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
JavaScript Node.js
import {
  KmsKeyringNode,
  buildClient,
  CommitmentPolicy,
} from '@aws-crypto/client-node'
                                
const { encrypt, decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
Fase 2: Costruisci il portachiavi.

Per decrittare i dati, passa il messaggio crittografato (result) restituito dalla funzione encrypt. Il messaggio crittografato include i dati crittografati, le chiavi di dati crittografate e i metadati importanti, inclusi il contesto di crittografia e la firma.

È inoltre necessario specificare un AWS KMS portachiavi durante la decrittografia. Puoi utilizzare lo stesso keyring usato per crittografare i dati o un keyring diverso. Per avere successo, almeno uno dei membri del portachiavi di decrittografia deve essere AWS KMS key in grado di decrittografare una delle chiavi di dati crittografate nel messaggio crittografato. Poiché non vengono generate chiavi di dati, non è necessario specificare una chiave generatore in un keyring di decrittazione. Se la specifichi, la chiave generatore e le chiavi aggiuntive vengono trattate allo stesso modo.

Per specificare un AWS KMS key portachiavi di decrittografia in, è necessario utilizzare la chiave. SDK di crittografia AWS per JavaScript ARN Altrimenti, non AWS KMS key viene riconosciuto. Per informazioni sull'identificazione di AWS KMS keys un AWS KMS portachiavi, consulta Identificazione AWS KMS keys in un portachiavi AWS KMS

Nota

Se usi lo stesso portachiavi per cifrare e decriptare, usa la chiave per identificarli ARNs all'interno del portachiavi. AWS KMS keys

In questo esempio, creiamo un portachiavi che include solo uno dei portachiavi di crittografia. AWS KMS keys Prima di eseguire questo codice, sostituite la chiave di esempio ARN con una chiave valida. Devi disporre dell'autorizzazione kms:Decrypt per la AWS KMS key.

JavaScript Browser

Inizia fornendo le credenziali nel browser. Gli SDK di crittografia AWS per JavaScript esempi utilizzano il webpack. DefinePlugin, che sostituisce le costanti delle credenziali con le credenziali effettive. Tuttavia puoi utilizzare qualsiasi metodo per fornire le credenziali. Quindi, utilizza le credenziali per creare un client. AWS KMS 

declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }

const clientProvider = getClient(KMS, {
  credentials: {
    accessKeyId,
    secretAccessKey,
    sessionToken
  }
})

Quindi, crea un AWS KMS portachiavi utilizzando il AWS KMS client. Questo esempio utilizza solo uno dei portachiavi AWS KMS keys di crittografia.

const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
JavaScript Node.js
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']

const keyring = new KmsKeyringNode({ keyIds })
Passaggio 3: decriptare i dati.

A questo punto, chiama la funzione decrypt. Passa il keyring di decrittazione appena creato (keyring) e il messaggio crittografato restituito dalla funzione encrypt (result). AWS Encryption SDK Utilizza il portachiavi per decrittografare una delle chiavi di dati crittografate. Quindi, utilizza la chiave di dati in testo normale per decrittare i dati.

Se la chiamata ha esito positivo, il campo plaintext contiene i dati di testo normale (decrittati). Il campo messageHeader contiene i metadati relativi al processo di decrittazione, incluso il contesto di crittografia utilizzato per decrittare i dati.

JavaScript Browser
const { plaintext, messageHeader } = await decrypt(keyring, result)
JavaScript Node.js
const { plaintext, messageHeader } = await decrypt(keyring, result)
Fase 4: Verificare il contesto di crittografia.

Il contesto di crittografia utilizzato per decrittare i dati è incluso nell'intestazione del messaggio (messageHeader) restituita dalla funzione decrypt. Prima che l'applicazione restituisca i dati di testo normale, verifica che il contesto di crittografia fornito durante la crittografia sia incluso nel contesto di crittografia utilizzato per la decrittazione. Una mancata corrispondenza potrebbe indicare che i dati sono stati manomessi o che non è stato decrittato il testo crittografato corretto.

Quando si verifica il contesto di crittografia, non è necessaria una corrispondenza esatta. Quando si utilizza un algoritmo di crittografia con la firma, il gestore dei materiali crittografici (CMM) aggiunge la chiave di firma pubblica al contesto di crittografia prima di crittografare il messaggio. Tuttavia, tutte le coppie di contesto di crittografia inviate devono essere incluse nel contesto di crittografia restituito.

Innanzitutto, ottieni il contesto di crittografia dall'intestazione del messaggio. Verifica quindi che ogni coppia chiave-valore nel contesto di crittografia originale (context) corrisponda a una coppia chiave-valore nel contesto di crittografia restituito (encryptionContext).

JavaScript Browser
const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
JavaScript Node.js
const { encryptionContext } = messageHeader

Object
  .entries(context)
  .forEach(([key, value]) => {
    if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})

Se il controllo del contesto di crittografia ha esito positivo, puoi restituire i dati di testo normale.