ApsaraDB RDS:Go driver

If you have the required master encryption key (MEK), alibabacloud-encdb-mysql-go-client can automatically decrypt ciphertext data and return plaintext data. The decryption process is transparent to your application, and you can connect the application to your always-confidential database with a few changes to the application code. This simplifies the usage of the always-confidential database feature.

Prerequisites

• The always-confidential database feature is enabled. For more information, see Enable the always-confidential database feature.

• The connection information for your always-confidential database is obtained. The information includes the domain name (host), port number (port), instance name (dbname), username (username), and password (password).

• A data protection rule is configured. For more information, see Configure a data protection rule.

Usage notes

• You must store the MEK and keep it confidential.

• The Go version must be 1.18 or later.

Procedure

Step 1: Obtain the driver

go get github.com/aliyun/alibabacloud-encdb-mysql-go-client@latest

Step 2: Query data from the client

• URL configurations

  You can use alibabacloud-encdb-mysql-go-client in the same manner as you use Go-MySQL-Driver. Before you use alibabacloud-encdb-mysql-go-client, you must configure the mek and encAlgo parameters in alibabacloud-encdb-mysql-go-client. mek specifies the MEK, and encAlgo specifies the encryption algorithm. The following parameters can be included in a URL to initiate a query: the domain name (hostname), port number (port), instance name (dbname), username (username), and password (password).

  mek := ...
  encAlgo := ...
  
  db, err := sql.Open("encmysql", "<username>:<password>@tcp(<hostname>:<port>)/<dbname>?MEK=<mek>&ENC_Algo=<encAlgo>")
  if err != nil {
   panic(err)
  }

  Note

  • You can use ampersands (&) to concatenate multiple parameters.

  • The mek parameter and other parameters are configured on the client side and transmitted to the server side by using envelope encryption. During the process, the confidentiality of the value of the mek parameter is ensured.

  The following table describes the mek and encAlgo parameters.

  Parameter	Example (string type)	Description
  MEK	00112233445566778899aabbccddeeff	The MEK that is specified by the data owner. MEK generation: You can use password generation tools such as OpenSSL and openssl rand -hex 16, call the random function in a programming language, or obtain keys from Key Management Service (KMS). Valid value: a 16-byte hexadecimal string that is 32 characters in length. Warning An MEK is the root credential that you use to access encrypted data. For security purposes, the RDS instance for which the always-confidential feature is enabled does not generate, store, or back up your MEK. You must generate an MEK and keep it confidential. If you lose your MEK, you can no longer access the data that is encrypted by using the MEK. We recommend that you back up your MEK.
  ENC_ALGO	SM4_128_CBC	The encryption algorithms that are used to protect the data. Valid values: Internationally accepted algorithms: AES_128_GCM AES_128_CTR AES_128_CBC AES_128_ECB (not recommended) SM algorithms: SM4_128_GCM (default) SM4_128_CTR SM4_128_CBC SM4_128_ECB (not recommended) Note The AES_128_ECB and SM4_128_ECB encryption algorithms cannot provide high security. We recommend that you select other encryption algorithms that provide higher security than the AES_128_ECB and SM4_128_ECB encryption algorithms. Optional. The default value is SM4_128_GCM.

• Complete sample code

  In this example, a demo project named go mod init demo is created.

  package main
  
  import (
   "database/sql"
   "fmt"
   _ "github.com/aliyun/alibabacloud-encdb-mysql-go-client"
  )
  
  func main() {
   // Update the connection information such as the domain name (hostname), port number (port), instance name (dbname), username (username), and password (password).
   
   db, err := sql.Open("encmysql", "<username>:<password>@tcp(<hostname>:<port>)/<dbname>?MEK=00112233445566778899aabbccddeeff&ENC_ALGO=SM4_128_CBC")
   if err != nil {
   panic(err)
   }
   _, err = db.Exec("DROP TABLE IF EXISTS test")
   if err != nil {
   panic(err)
   }
   _, err = db.Exec(`create table test(a int, b text, c float)`)
   if err != nil {
   panic(err)
   }
   _, err = db.Exec(`insert into test set a = 0, b = 'test', c = 0.0`)
   if err != nil {
   panic(err)
   }
   rows, err := db.Query("SELECT * FROM test")
   rows.Next()
   var a int
   var b string
   var c float32
  
   err = rows.Scan(&a, &b, &c)
   fmt.Printf("read data: %d %s %f\n", a, b, c)
  }

  After the preceding code is called, the decrypted result similar to the following information is returned:

  read data: 0 test 0.000000

References

• EncJDBC

• EncDB SDK

• Enable the always-confidential database feature

• Configure a data protection rule