Couchbase Field Level Encrytpion

Couchbase 支持 Field Level Encryption。本部分介绍如何配合 Spring Data Couchbase 使用。

Couchbase supports Field Level Encryption. This section documents how to use it with Spring Data Couchbase.

Requirements

  • Spring Data Couchbase 5.0.0-RC1 or above.

Overview

使用 com.couchbase.client.java.encryption.annotation.Encrypted (@Encrypted) 注释的字段将在写入时自动加密，并在读取时自动解密。未加密的字段可以通过指定 @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED) 迁移到加密。

Fields annotated with com.couchbase.client.java.encryption.annotation.Encrypted (@Encrypted) will be automatically encrypted on write and decrypted on read. Unencrypted fields can be migrated to encrypted by specifying @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED).

Getting Started & Configuration

Dependencies

场级加密可通过依赖项获取 (参见 Field Level Encryption)

Field Level Encryption is available with the dependency ( see Field Level Encryption )

    <groupId>com.couchbase.client</groupId>
    <artifactId>couchbase-encryption</artifactId>

HashiCorp Vault Transit 集成需要 Spring Vault

HashiCorp Vault Transit integration requires Spring Vault

    <groupId>org.springframework.vault</groupId>
    <artifactId>spring-vault-core</artifactId>

Providing a CryptoManager

必须通过覆盖 AbstractCouchbaseConfiguration 中的 cryptoManager() 方法来提供一个 CryptoManager。Spring Data Couchbase 和由 CouchbaseClientFactory 发出的 Couchbase Java SDK 直接调用将使用此 CryptoManager。

A CryptoManager needs to be provided by overriding the cryptoManager() method in AbstractCouchbaseConfiguration. This CryptoManager will be used by Spring Data Couchbase and also by Couchbase Java SDK direct calls made from a CouchbaseClientFactory.

@Override
protected CryptoManager cryptoManager() {
  KeyStore javaKeyStore = KeyStore.getInstance("MyKeyStoreType");
  FileInputStream fis = new java.io.FileInputStream("keyStoreName");
  char[] password = { 'a', 'b', 'c' };
  javaKeyStore.load(fis, password);
  Keyring keyring = new KeyStoreKeyring(javaKeyStore, keyName -> "swordfish");

  // AES-256 authenticated with HMAC SHA-512. Requires a 64-byte key.
  AeadAes256CbcHmacSha512Provider provider = AeadAes256CbcHmacSha512Provider.builder().keyring(keyring).build();

  CryptoManager cryptoManager = DefaultCryptoManager.builder().decrypter(provider.decrypter())
    .defaultEncrypter(provider.encrypterForKey("myKey")).build();
  return cryptoManager;
}

Defining a Field as Encrypted.

  1. @Encrypted defines a field as encrypted.

  2. @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED) defines a field that may or may not be encrypted when read. It will be encrypted when written.

  3. @Encrypted(encrypter = "<encrypterAlias>") specifies the alias of the encrypter to use for encryption. Note this is not the algorithm, but the name specified when adding the encrypter to the CryptoManager.

Example

Example 1. AbstractCouchbaseConfiguration
@Configuration
@EnableCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
@EnableReactiveCouchbaseRepositories("<parent-dir-of-repository-interfaces>")
static class Config extends AbstractCouchbaseConfiguration {

  // Usual Setup
  @Override public String getConnectionString() { /* ... */ }
  @Override public String getUserName() { /* ... */ }
  @Override public String getPassword() { /* ... */ }
  @Override public String getBucketName() { /* ... */ }

  /* provide a cryptoManager */
  @Override
  protected CryptoManager cryptoManager() {
    KeyStore javaKeyStore = KeyStore.getInstance("MyKeyStoreType");
    FileInputStream fis = new java.io.FileInputStream("keyStoreName");
    char[] password = { 'a', 'b', 'c' };
    javaKeyStore.load(fis, password);
    Keyring keyring = new KeyStoreKeyring(javaKeyStore, keyName -> "swordfish");

    // AES-256 authenticated with HMAC SHA-512. Requires a 64-byte key.
    AeadAes256CbcHmacSha512Provider provider = AeadAes256CbcHmacSha512Provider.builder().keyring(keyring).build();

    CryptoManager cryptoManager = DefaultCryptoManager.builder().decrypter(provider.decrypter())
      .defaultEncrypter(provider.encrypterForKey("myKey")).build();
    return cryptoManager;
  }

}
Example 2. The Annotation in the Document
@Document
public class AddressWithEncStreet extends Address {

    private @Encrypted String encStreet;
    .
    .
Example 3. Usage in Code
AddressWithEncStreet address = new AddressWithEncStreet(); // plaintext address with encrypted street
address.setCity("Santa Clara");
address.setEncStreet("Olcott Street");
addressEncryptedRepository.save(address);
Example 4. Resulting Document
{
  "_class": "AddressWithEncStreet",
   "city": "Santa Clara",
   "encrypted$encStreet": {
     "alg": "AEAD_AES_256_CBC_HMAC_SHA512",
     "ciphertext": "A/tJALmtixTxqj77ZUcUgMklIt3372DKD7l5FvbCzHNJMplbgQEv0RgSbxIfiRNr+uW2H7cokkcCW/F5YnQoXA==",
     "kid": "myKey"
   }
}