Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Menggunakan pustaka enkripsi sisi klien Java untuk DynamoDB
****
| |
| --- |
| Pustaka enkripsi sisi klien kami diubah namanya menjadi SDK Enkripsi AWS Database. Panduan pengembang ini masih memberikan informasi tentang Klien Enkripsi [DynamoDB](legacy-dynamodb-encryption-client.md). |
Topik ini menjelaskan beberapa fungsi dan kelas pembantu di versi 3. *x* dari pustaka enkripsi sisi klien Java untuk DynamoDB.
Untuk detail tentang pemrograman dengan pustaka enkripsi sisi klien Java untuk DynamoDB, lihat contoh Java, [contoh Java](java-examples.md) di repositori -dynamodb [aktif](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples). aws-database-encryption-sdk GitHub
**Topics**
+ [Enkriptor item](#ddb-item-encryptors)
+ [Tindakan atribut](#ddb-attribute-actions)
+ [Konfigurasi enkripsi](#ddb-config-encrypt)
+ [Memperbarui item](#ddb-update-items)
+ [Mendekripsi set yang ditandatangani](#ddb-java-signed-sets)
## Enkriptor item
Pada intinya, AWS Database Encryption SDK untuk DynamoDB adalah enkripsi item. Anda dapat menggunakan versi 3. *x* pustaka enkripsi sisi klien Java untuk DynamoDB untuk mengenkripsi, menandatangani, memverifikasi, dan mendekripsi item tabel DynamoDB Anda dengan cara berikut.
**Klien yang Ditingkatkan DynamoDB**
Anda dapat mengkonfigurasi [DynamoDB Enhanced Client dengan untuk secara otomatis mengenkripsi dan menandatangani item sisi klien dengan `DynamoDbEncryptionInterceptor` permintaan DynamoDB](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) Anda. `PutItem` Dengan DynamoDB Enhanced Client, Anda dapat menentukan tindakan atribut Anda menggunakan kelas data [beranotasi](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean). Sebaiknya gunakan DynamoDB Enhanced Client bila memungkinkan.
[DynamoDB Enhanced Client tidak mendukung enkripsi yang dapat dicari.](searchable-encryption.md)
SDK Enkripsi AWS Database tidak mendukung anotasi pada atribut [bersarang](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html).
**API DynamoDB tingkat rendah**
Anda dapat mengonfigurasi API [DynamoDB tingkat rendah dengan untuk secara otomatis mengenkripsi dan menandatangani item `DynamoDbEncryptionInterceptor` sisi klien dengan permintaan DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html) Anda. `PutItem`
[Anda harus menggunakan API DynamoDB tingkat rendah untuk menggunakan enkripsi yang dapat dicari.](searchable-encryption.md)
**Tingkat yang lebih rendah `DynamoDbItemEncryptor`**
Tingkat yang lebih rendah `DynamoDbItemEncryptor` secara langsung mengenkripsi dan menandatangani atau mendekripsi dan memverifikasi item tabel Anda tanpa memanggil DynamoDB. Itu tidak membuat DynamoDB atau `PutItem` permintaan`GetItem`. Misalnya, Anda dapat menggunakan level yang lebih rendah `DynamoDbItemEncryptor` untuk langsung mendekripsi dan memverifikasi item DynamoDB yang telah Anda ambil.
Tingkat yang lebih rendah `DynamoDbItemEncryptor` tidak mendukung enkripsi yang dapat [dicari](searchable-encryption.md).
## Tindakan atribut dalam SDK Enkripsi AWS Database untuk DynamoDB
[Tindakan atribut](concepts.md#crypt-actions) menentukan nilai atribut mana yang dienkripsi dan ditandatangani, yang hanya ditandatangani, yang ditandatangani dan disertakan dalam konteks enkripsi, dan mana yang diabaikan.
**catatan**
Untuk menggunakan tindakan `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` kriptografi, Anda harus menggunakan SDK Enkripsi AWS Database versi 3.3 atau yang lebih baru. Terapkan versi baru ke semua pembaca sebelum [memperbarui model data Anda](ddb-update-data-model.md) untuk disertakan`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
Jika Anda menggunakan API DynamoDB tingkat rendah atau level yang `DynamoDbItemEncryptor` lebih rendah, Anda harus menentukan tindakan atribut secara manual. [Jika Anda menggunakan DynamoDB Enhanced Client, Anda dapat menentukan tindakan atribut secara manual, atau Anda dapat menggunakan kelas data beranotasi untuk menghasilkan. `TableSchema`](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html) Untuk menyederhanakan proses konfigurasi, kami sarankan menggunakan kelas data beranotasi. Bila Anda menggunakan kelas data beranotasi, Anda hanya perlu memodelkan objek Anda sekali.
**catatan**
Setelah menentukan tindakan atribut, Anda harus menentukan atribut mana yang dikecualikan dari tanda tangan. Untuk mempermudah menambahkan atribut unsigned baru di masa mendatang, sebaiknya pilih awalan yang berbeda (seperti "`:`“) untuk mengidentifikasi atribut unsigned Anda. Sertakan awalan ini dalam nama atribut untuk semua atribut yang ditandai `DO_NOTHING` saat Anda menentukan skema DynamoDB dan tindakan atribut.
### Gunakan kelas data beranotasi
Gunakan [kelas data beranotasi](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) untuk menentukan tindakan atribut Anda dengan DynamoDB Enhanced Client dan. `DynamoDbEncryptionInterceptor` SDK Enkripsi AWS Database untuk DynamoDB menggunakan anotasi [atribut DynamoDB standar yang menentukan jenis atribut](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html) untuk menentukan cara melindungi atribut. Secara default, semua atribut dienkripsi dan ditandatangani kecuali kunci utama, yang ditandatangani tetapi tidak dienkripsi.
**catatan**
Untuk menggunakan tindakan `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` kriptografi, Anda harus menggunakan SDK Enkripsi AWS Database versi 3.3 atau yang lebih baru. Terapkan versi baru ke semua pembaca sebelum [memperbarui model data Anda](ddb-update-data-model.md) untuk disertakan`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
Lihat [SimpleClass.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) di repositori aws-database-encryption-sdk -dynamodb untuk panduan GitHub lebih lanjut tentang anotasi DynamoDB Enhanced Client.
Secara default, atribut kunci primer ditandatangani tetapi tidak dienkripsi (`SIGN_ONLY`) dan semua atribut lainnya dienkripsi dan ditandatangani (). `ENCRYPT_AND_SIGN` Jika Anda mendefinisikan atribut apa pun sebagai`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, maka atribut partisi dan sortir juga harus`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Untuk menentukan pengecualian, gunakan anotasi enkripsi yang ditentukan dalam pustaka enkripsi sisi klien Java untuk DynamoDB. Misalnya, jika Anda ingin atribut tertentu hanya ditandatangani, gunakan `@DynamoDbEncryptionSignOnly` anotasi. Jika Anda ingin atribut tertentu ditandatangani dan disertakan dalam konteks enkripsi, gunakan`@DynamoDbEncryptionSignAndIncludeInEncryptionContext`. Jika Anda ingin atribut tertentu tidak ditandatangani atau dienkripsi (`DO_NOTHING`), gunakan anotasi`@DynamoDbEncryptionDoNothing`.
**catatan**
SDK Enkripsi AWS Database tidak mendukung anotasi pada atribut [bersarang](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html).
Contoh berikut menunjukkan anotasi yang digunakan untuk mendefinisikan`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, dan `DO_NOTHING` atribut tindakan. Untuk contoh yang menunjukkan anotasi yang digunakan untuk mendefinisikan`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, lihat [SimpleClass4.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.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;
}
}
```
Gunakan kelas data beranotasi Anda untuk membuat `TableSchema` seperti yang ditunjukkan dalam cuplikan berikut.
```
final TableSchema tableSchema = TableSchema.fromBean(SimpleClass.class);
```
### Tentukan tindakan atribut Anda secara manual
Untuk menentukan tindakan atribut secara manual, buat `Map` objek di mana pasangan nama-nilai mewakili nama atribut dan tindakan yang ditentukan.
Tentukan `ENCRYPT_AND_SIGN` untuk mengenkripsi dan menandatangani atribut. Tentukan `SIGN_ONLY` untuk menandatangani, tetapi tidak mengenkripsi, atribut. Tentukan `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` untuk menandatangani atribut dan sertakan dalam konteks enkripsi. Anda tidak dapat mengenkripsi atribut tanpa menandatanganinya juga. Tentukan `DO_NOTHING` untuk mengabaikan atribut.
Partisi dan atribut sortir harus salah satu `SIGN_ONLY` atau`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Jika Anda mendefinisikan atribut apa pun sebagai`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, maka atribut partisi dan sortir juga harus`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
**catatan**
Untuk menggunakan tindakan `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` kriptografi, Anda harus menggunakan SDK Enkripsi AWS Database versi 3.3 atau yang lebih baru. Terapkan versi baru ke semua pembaca sebelum [memperbarui model data Anda](ddb-update-data-model.md) untuk disertakan`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.
```
final Map 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);
```
## Konfigurasi enkripsi dalam SDK Enkripsi AWS Database untuk DynamoDB
Bila Anda menggunakan AWS Database Encryption SDK, Anda harus secara eksplisit menentukan konfigurasi enkripsi untuk tabel DynamoDB Anda. Nilai yang diperlukan dalam konfigurasi enkripsi Anda bergantung pada apakah Anda mendefinisikan tindakan atribut secara manual atau dengan kelas data beranotasi.
Cuplikan berikut mendefinisikan konfigurasi enkripsi tabel DynamoDB menggunakan DynamoDB Enhanced Client, [https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html)dan mengizinkan atribut unsigned yang ditentukan oleh awalan yang berbeda.
```
final Map 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());
```
**Nama tabel logis**
Sebuah nama tabel logis untuk tabel DynamoDB Anda.
Nama tabel logis terikat secara kriptografis ke semua data yang disimpan dalam tabel untuk menyederhanakan operasi pemulihan DynamoDB. Kami sangat menyarankan untuk menentukan nama tabel DynamoDB Anda sebagai nama tabel logis saat Anda pertama kali menentukan konfigurasi enkripsi Anda. Anda harus selalu menentukan nama tabel logis yang sama. Agar dekripsi berhasil, nama tabel logis harus sesuai dengan nama yang ditentukan pada enkripsi. Jika nama tabel DynamoDB Anda berubah setelah [memulihkan tabel DynamoDB Anda dari cadangan, nama tabel](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html) logis memastikan bahwa operasi dekripsi masih mengenali tabel.
**Atribut yang tidak ditandatangani yang diizinkan**
Atribut yang ditandai `DO_NOTHING` dalam tindakan atribut Anda.
Atribut unsigned yang diizinkan memberi tahu klien atribut mana yang dikecualikan dari tanda tangan. Klien mengasumsikan bahwa semua atribut lainnya termasuk dalam tanda tangan. Kemudian, saat mendekripsi catatan, klien menentukan atribut mana yang perlu diverifikasi dan mana yang harus diabaikan dari atribut unsigned yang diizinkan yang Anda tentukan. Anda tidak dapat menghapus atribut dari atribut yang tidak ditandatangani yang diizinkan.
Anda dapat menentukan atribut unsigned yang diizinkan secara eksplisit dengan membuat array yang mencantumkan semua atribut Anda. `DO_NOTHING` Anda juga dapat menentukan awalan yang berbeda saat menamai `DO_NOTHING` atribut Anda dan menggunakan awalan untuk memberi tahu klien atribut mana yang tidak ditandatangani. Kami sangat menyarankan untuk menentukan awalan yang berbeda karena menyederhanakan proses penambahan `DO_NOTHING` atribut baru di masa depan. Untuk informasi selengkapnya, lihat [Memperbarui model data Anda](ddb-update-data-model.md).
Jika Anda tidak menentukan awalan untuk semua `DO_NOTHING` atribut, Anda dapat mengonfigurasi `allowedUnsignedAttributes` array yang secara eksplisit mencantumkan semua atribut yang diharapkan klien tidak ditandatangani saat bertemu dengan mereka pada dekripsi. Anda hanya harus secara eksplisit mendefinisikan atribut unsigned yang diizinkan jika benar-benar diperlukan.
**Konfigurasi Pencarian (Opsional)**
`SearchConfig`Mendefinisikan versi [beacon](using-beacons.md#beacon-version).
`SearchConfig`Harus ditentukan untuk menggunakan [enkripsi yang dapat dicari](searchable-encryption.md) atau suar yang [ditandatangani](configure.md#signed-beacons).
**Suite Algoritma (Opsional)**
`algorithmSuiteId`Mendefinisikan algoritma mana yang sesuai dengan AWS Database Encryption SDK yang digunakan.
Kecuali Anda secara eksplisit menentukan rangkaian algoritme alternatif, SDK Enkripsi AWS Database menggunakan rangkaian algoritme [default](supported-algorithms.md#recommended-algorithms). [Rangkaian algoritma default menggunakan algoritma AES-GCM dengan derivasi kunci, [tanda tangan digital](concepts.md#digital-sigs), dan komitmen kunci.](concepts.md#key-commitment) Meskipun rangkaian algoritme default kemungkinan cocok untuk sebagian besar aplikasi, Anda dapat memilih rangkaian algoritma alternatif. Misalnya, beberapa model kepercayaan akan dipenuhi oleh rangkaian algoritma tanpa tanda tangan digital. Untuk informasi tentang rangkaian algoritme yang didukung SDK Enkripsi AWS Database, lihat[Rangkaian algoritme yang didukung di SDK Enkripsi AWS Database](supported-algorithms.md).
Untuk memilih [rangkaian algoritma AES-GCM tanpa tanda tangan digital ECDSA](supported-algorithms.md#other-algorithms), sertakan cuplikan berikut dalam konfigurasi enkripsi tabel Anda.
```
.algorithmSuiteId(
DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)
```
## Memperbarui item dengan AWS Database Encryption SDK
SDK Enkripsi AWS Database tidak mendukung [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) untuk item yang telah dienkripsi atau ditandatangani. Untuk memperbarui item terenkripsi atau ditandatangani, Anda harus menggunakan [ddb](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html):. PutItem Saat Anda menentukan kunci utama yang sama dengan item yang ada dalam `PutItem` permintaan Anda, item baru sepenuhnya menggantikan item yang ada. Anda juga dapat menggunakan [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) untuk menghapus dan mengganti semua atribut yang disimpan setelah memperbarui item Anda.
## Mendekripsi set yang ditandatangani
Di SDK Enkripsi AWS Database versi 3.0.0 dan 3.1.0, jika Anda menentukan atribut [tipe set](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes) sebagai`SIGN_ONLY`, nilai himpunan akan dikanonikalisasi dalam urutan yang disediakan. DynamoDB tidak mempertahankan urutan set. Akibatnya, ada kemungkinan validasi tanda tangan dari item yang berisi set akan gagal. Validasi tanda tangan gagal ketika nilai set dikembalikan dalam urutan yang berbeda dari yang diberikan ke SDK Enkripsi AWS Database, meskipun atribut set berisi nilai yang sama.
**catatan**
Versi 3.1.1 dan yang lebih baru dari AWS Database Encryption SDK mengkanonikalisasikan nilai semua atribut tipe set, sehingga nilai dibaca dalam urutan yang sama dengan yang ditulis ke DynamoDB.
Jika validasi tanda tangan gagal, operasi dekripsi gagal dan mengembalikan pesan kesalahan berikut.
| |
| --- |
| software.amazon.cryptography.dbencryptionsdk.structuredencryption.model. StructuredEncryptionException: Tidak ada tag penerima yang cocok. |
Jika Anda menerima pesan kesalahan di atas, dan yakin bahwa item yang Anda coba dekripsi menyertakan set yang ditandatangani menggunakan versi 3.0.0 atau 3.1.0, lihat [DecryptWithPermute](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/tree/v3.1.1/DecryptWithPermute)direktori repositori aws-database-encryption-sdk -dynamodb-java untuk detail tentang cara berhasil memvalidasi set. GitHub