How do I use the SDK for Java to create an encrypted data table? - Tablestore

Tablestore provides the table encryption feature to encrypt a table when the table is saved to a disk. This ensures the security of table data. When you create a table, you can configure table encryption. Tablestore provides two encryption methods: encryption based on Key Management Service (KMS) key and encryption based on Bring Your Own Key (BYOK).

Prerequisites

A Tablestore instance is created in the Tablestore console. For more information, see Create a Tablestore instance.
A client is initialized. For more information, see Initialize an OTSClient instance.

Encryption based on KMS

To enable KMS key-based encryption for a data table, you must activate KMS. However, you do not need to create a KMS instance. After you create a data table, you can call the DescribeTable operation to query the encryption configuration of the table.

The following sample code shows how to enable KMS key-based encryption for a data table when you create the data table. The primary key of the data table is pk and of the STRING type. For the values of the attribute columns, only the latest version of data is retained, and the data never expires.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // If you want to configure data encryption, configure encryption-related parameters in the CreateTable request. The following encryption methods are supported: KMS key-based encryption and BYOK-based encryption. In this example, KMS key-based encryption is enabled. 
    SSESpecification sseKms = new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE);
    // Add a primary key column to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING)); 
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    // Specify the reserved read throughput and reserved write throughout. The values must be set to 0 for data tables in capacity instances and can be set to non-zero values for data tables in high-performance instances. 
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); 
    request.setSseSpecification(sseKms);
    client.createTable(request);
}

Encryption based on BYOK

Create a software-protected key in the KMS console. For more information, see the "Software-protected key" section of the Getting started with keys topic.
Create a RAM role and grant permissions to the RAM role.
1. Create a RAM role. For more information, see Create a RAM role for a trusted Alibaba Cloud account.
  Set the role name to AliyunOTSAccessingKMS.
2. Create a custom policy that contains the KMS encryption and decryption permissions. For information about how to create a custom policy, see the "Create a custom policy on the JSON tab" section of the Create custom policies topic.
  Set the policy name to otskmspolicytest. Sample policy:
```
{
    "Version": "1",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
```
3. Attach the otskmspolicytest policy to the AliyunOTSAccessingKMS role. For more information, see Grant permissions to a RAM role.
  After you complete the authorization, record the ARN of the RAM role. The ARN indicates the ID of the RAM role.
4. Modify the trust policy of the RAM role. For more information, see Edit the trust policy of a RAM role.
  Sample trust policy:
```
{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "ots.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}
```

Create a data table and configure encryption-related parameters.

Create a data table and enable BYOK-based encryption. After you create a data table, you can call the DescribeTable operation to query the encryption configuration of the table.

The following sample code shows how to enable BYOK-based encryption for a data table when you create the data table. The primary key of the data table is pk and of the STRING type. For the values of the attribute columns, only the latest version of data is retained, and the data never expires.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // If you want to configure data encryption, configure encryption-related parameters in the CreateTable request. The following encryption methods are supported: KMS key-based encryption and BYOK-based encryption. 
    // Set the keyId parameter to the ID of the software-protected key that you created in the KMS console in Step 1. 
    String keyId="key-hzz65****************";
    // Set the roleArn parameter to the ARN of the RAM role that you recorded in Step 2. 
    String roleArn="acs:ram::****************:role/aliyunotsaccessingkms";
    // In this example, BYOK-based encryption is enabled. 
    // Set the keyId parameter to the ID of the custom key in KMS. Set the roleArn parameter to the ARN of the RAM role that you want to use. You must create a RAM role and record the ARN of the RAM role. 
    SSESpecification sseByok = new SSESpecification(true, SSEKeyType.SSE_BYOK, keyId, roleArn);
    // Add a primary key column to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING)); 
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); // Specify the reserved read throughput and reserved write throughout. The values must be set to 0 for data tables in capacity instances and can be set to non-zero values for data tables in high-performance instances. 
    request.setSseSpecification(sseByok);
    client.createTable(request);
}