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 the "Step 2: Create an instance" section of the Use the Wide Column model in the Tablestore console topic.
A client is initialized. For more information, see Initialization.

Encryption based on KMS

To enable KMS key-based encryption for a data table, you need to 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 provides an example on 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 modes 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 versions that can be retained for each column. A value of 1 specifies that only the latest version 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 Key Management" topic.
Create a Resource Access Management (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 more information, see the Create a custom policy on the JSON tab section of the "Create a custom policy" 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 Alibaba Cloud Resource Name (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 provides an example on 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 modes 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 need to 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 versions that can be retained for each column. A value of 1 specifies that only the latest version 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);
}