ほとんどのデータ暗号化ユースケースでは、AES128_GCM 鍵タイプを使用する AEAD プリミティブをおすすめします。
関連データを伴う認証付き暗号化（AEAD）は、ほとんどのユースケースで最もシンプルで適切なプリミティブです。AEAD は秘密性と真正性を提供し、平文（暗号化の入力）が同じであっても、メッセージに常に異なる暗号文（暗号化された出力）が存在するようにします。対称暗号化は、暗号化と復号の両方に単一の鍵を使用します。
次の例では、AEAD プリミティブの使用を開始します。
C++
// A command-line utility for testing Tink AEAD.
#include <iostream>
#include <memory>
#include <ostream>
#include <string>
#include "absl/flags/flag.h"
#include "absl/flags/parse.h"
#include "absl/log/check.h"
#include "absl/strings/string_view.h"
#include "tink/aead.h"
#include "tink/aead/aead_config.h"
#include "tink/config/global_registry.h"
#include "util/util.h"
#include "tink/keyset_handle.h"
#include "tink/util/status.h"
ABSL_FLAG(std::string, keyset_filename, "", "Keyset file in JSON format");
ABSL_FLAG(std::string, mode, "", "Mode of operation {encrypt|decrypt}");
ABSL_FLAG(std::string, input_filename, "", "Filename to operate on");
ABSL_FLAG(std::string, output_filename, "", "Output file name");
ABSL_FLAG(std::string, associated_data, "",
"Associated data for AEAD (default: empty");
namespace {
using ::crypto::tink::Aead;
using ::crypto::tink::AeadConfig;
using ::crypto::tink::KeysetHandle;
using ::crypto::tink::util::Status;
using ::crypto::tink::util::StatusOr;
constexpr absl::string_view kEncrypt = "encrypt";
constexpr absl::string_view kDecrypt = "decrypt";
void ValidateParams() {
// ...
}
} // namespace
namespace tink_cc_examples {
// AEAD example CLI implementation.
Status AeadCli(absl::string_view mode, const std::string& keyset_filename,
const std::string& input_filename,
const std::string& output_filename,
absl::string_view associated_data) {
Status result = AeadConfig::Register();
if (!result.ok()) return result;
// Read the keyset from file.
StatusOr<std::unique_ptr<KeysetHandle>> keyset_handle =
ReadJsonCleartextKeyset(keyset_filename);
if (!keyset_handle.ok()) return keyset_handle.status();
// Get the primitive.
StatusOr<std::unique_ptr<Aead>> aead =
(*keyset_handle)
->GetPrimitive<crypto::tink::Aead>(
crypto::tink::ConfigGlobalRegistry());
if (!aead.ok()) return aead.status();
// Read the input.
StatusOr<std::string> input_file_content = ReadFile(input_filename);
if (!input_file_content.ok()) return input_file_content.status();
// Compute the output.
std::string output;
if (mode == kEncrypt) {
StatusOr<std::string> encrypt_result =
(*aead)->Encrypt(*input_file_content, associated_data);
if (!encrypt_result.ok()) return encrypt_result.status();
output = encrypt_result.value();
} else { // operation == kDecrypt.
StatusOr<std::string> decrypt_result =
(*aead)->Decrypt(*input_file_content, associated_data);
if (!decrypt_result.ok()) return decrypt_result.status();
output = decrypt_result.value();
}
// Write the output to the output file.
return WriteToFile(output, output_filename);
}
} // namespace tink_cc_examples
int main(int argc, char** argv) {
absl::ParseCommandLine(argc, argv);
ValidateParams();
std::string mode = absl::GetFlag(FLAGS_mode);
std::string keyset_filename = absl::GetFlag(FLAGS_keyset_filename);
std::string input_filename = absl::GetFlag(FLAGS_input_filename);
std::string output_filename = absl::GetFlag(FLAGS_output_filename);
std::string associated_data = absl::GetFlag(FLAGS_associated_data);
std::clog << "Using keyset from file " << keyset_filename << " to AEAD-"
<< mode << " file " << input_filename << " with associated data '"
<< associated_data << "'." << '\n';
std::clog << "The resulting output will be written to " << output_filename
<< '\n';
CHECK_OK(tink_cc_examples::AeadCli(mode, keyset_filename, input_filename,
output_filename, associated_data));
return 0;
}
Go
import (
"bytes"
"fmt"
"log"
"github.com/tink-crypto/tink-go/v2/aead"
"github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset"
"github.com/tink-crypto/tink-go/v2/keyset"
)
func Example() {
// A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
// that this keyset has the secret key information in cleartext.
jsonKeyset := `{
"key": [{
"keyData": {
"keyMaterialType":
"SYMMETRIC",
"typeUrl":
"type.googleapis.com/google.crypto.tink.AesGcmKey",
"value":
"GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg=="
},
"keyId": 294406504,
"outputPrefixType": "TINK",
"status": "ENABLED"
}],
"primaryKeyId": 294406504
}`
// Create a keyset handle from the cleartext keyset in the previous
// step. The keyset handle provides abstract access to the underlying keyset to
// limit the exposure of accessing the raw key material. WARNING: In practice,
// it is unlikely you will want to use a insecurecleartextkeyset, as it implies
// that your key material is passed in cleartext, which is a security risk.
// Consider encrypting it with a remote key in Cloud KMS, AWS KMS or HashiCorp Vault.
// See https://github.com/google/tink/blob/master/docs/GOLANG-HOWTO.md#storing-and-loading-existing-keysets.
keysetHandle, err := insecurecleartextkeyset.Read(
keyset.NewJSONReader(bytes.NewBufferString(jsonKeyset)))
if err != nil {
log.Fatal(err)
}
// Retrieve the AEAD primitive we want to use from the keyset handle.
primitive, err := aead.New(keysetHandle)
if err != nil {
log.Fatal(err)
}
// Use the primitive to encrypt a message. In this case the primary key of the
// keyset will be used (which is also the only key in this example).
plaintext := []byte("message")
associatedData := []byte("associated data")
ciphertext, err := primitive.Encrypt(plaintext, associatedData)
if err != nil {
log.Fatal(err)
}
// Use the primitive to decrypt the message. Decrypt finds the correct key in
// the keyset and decrypts the ciphertext. If no key is found or decryption
// fails, it returns an error.
decrypted, err := primitive.Decrypt(ciphertext, associatedData)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(decrypted))
// Output: message
}
Java
package aead;
import static java.nio.charset.StandardCharsets.UTF_8;
import com.google.crypto.tink.Aead;
import com.google.crypto.tink.InsecureSecretKeyAccess;
import com.google.crypto.tink.KeysetHandle;
import com.google.crypto.tink.TinkJsonProtoKeysetFormat;
import com.google.crypto.tink.aead.AeadConfig;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
/**
* A command-line utility for encrypting small files with AEAD.
*
* <p>It loads cleartext keys from disk - this is not recommended!
*
* <p>It requires the following arguments:
*
* <ul>
* <li>mode: Can be "encrypt" or "decrypt" to encrypt/decrypt the input to the output.
* <li>key-file: Read the key material from this file.
* <li>input-file: Read the input from this file.
* <li>output-file: Write the result to this file.
* <li>[optional] associated-data: Associated data used for the encryption or decryption.
*/
public final class AeadExample {
private static final String MODE_ENCRYPT = "encrypt";
private static final String MODE_DECRYPT = "decrypt";
public static void main(String[] args) throws Exception {
if (args.length != 4 && args.length != 5) {
System.err.printf("Expected 4 or 5 parameters, got %d\n", args.length);
System.err.println(
"Usage: java AeadExample encrypt/decrypt key-file input-file output-file"
+ " [associated-data]");
System.exit(1);
}
String mode = args[0];
Path keyFile = Paths.get(args[1]);
Path inputFile = Paths.get(args[2]);
Path outputFile = Paths.get(args[3]);
byte[] associatedData = new byte[0];
if (args.length == 5) {
associatedData = args[4].getBytes(UTF_8);
}
// Register all AEAD key types with the Tink runtime.
AeadConfig.register();
// Read the keyset into a KeysetHandle.
KeysetHandle handle =
TinkJsonProtoKeysetFormat.parseKeyset(
new String(Files.readAllBytes(keyFile), UTF_8), InsecureSecretKeyAccess.get());
// Get the primitive.
Aead aead = handle.getPrimitive(Aead.class);
// Use the primitive to encrypt/decrypt files.
if (MODE_ENCRYPT.equals(mode)) {
byte[] plaintext = Files.readAllBytes(inputFile);
byte[] ciphertext = aead.encrypt(plaintext, associatedData);
Files.write(outputFile, ciphertext);
} else if (MODE_DECRYPT.equals(mode)) {
byte[] ciphertext = Files.readAllBytes(inputFile);
byte[] plaintext = aead.decrypt(ciphertext, associatedData);
Files.write(outputFile, plaintext);
} else {
System.err.println("The first argument must be either encrypt or decrypt, got: " + mode);
System.exit(1);
}
}
private AeadExample() {}
}
Obj-C
Python
import tink
from tink import aead
from tink import secret_key_access
def example():
"""Encrypt and decrypt using AEAD."""
# Register the AEAD key managers. This is needed to create an Aead primitive
# later.
aead.register()
# A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note
# that this keyset has the secret key information in cleartext.
keyset = r"""{
"key": [{
"keyData": {
"keyMaterialType":
"SYMMETRIC",
"typeUrl":
"type.googleapis.com/google.crypto.tink.AesGcmKey",
"value":
"GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg=="
},
"keyId": 294406504,
"outputPrefixType": "TINK",
"status": "ENABLED"
}],
"primaryKeyId": 294406504
}"""
# Create a keyset handle from the cleartext keyset in the previous
# step. The keyset handle provides abstract access to the underlying keyset to
# limit access of the raw key material. WARNING: In practice, it is unlikely
# you will want to use a cleartext_keyset_handle, as it implies that your key
# material is passed in cleartext, which is a security risk.
keyset_handle = tink.json_proto_keyset_format.parse(
keyset, secret_key_access.TOKEN
)
# Retrieve the Aead primitive we want to use from the keyset handle.
primitive = keyset_handle.primitive(aead.Aead)
# Use the primitive to encrypt a message. In this case the primary key of the
# keyset will be used (which is also the only key in this example).
ciphertext = primitive.encrypt(b'msg', b'associated_data')
# Use the primitive to decrypt the message. Decrypt finds the correct key in
# the keyset and decrypts the ciphertext. If no key is found or decryption
# fails, it raises an error.
output = primitive.decrypt(ciphertext, b'associated_data')
AEAD
関連データを伴う認証付き暗号化（AEAD）プリミティブは、データ暗号化の最も一般的なプリミティブであり、ほとんどのニーズに適しています。
AEAD には次の特性があります。
- Secrecy: 平文については、長さ以外は何もわかりません。
- 真正性: 暗号テキストの基になる暗号化された平文を検出されることなく変更することはできません。
- 対称: 平文の暗号化と暗号テキストの復号は、同じ鍵で行われます。
- ランダム化: 暗号化はランダム化されます。同じ平文の 2 つのメッセージがあっても、暗号テキストは異なります。攻撃者は、特定の平文に対応する暗号テキストを認識できません。これを回避するには、代わりに 確定的 AEAD を使用します。
関連データ
AEAD を使用すると、暗号テキストを特定の関連データに関連付けることができます。user-id フィールドと encrypted-medical-history フィールドを含むデータベースがあるとします。このシナリオでは、encrypted-medical-history を暗号化するときに、user-id を関連データとして使用できます。これにより、攻撃者がユーザー間で医療履歴を移動させることはできません。
キータイプを選択する
ほとんどの用途では AES128_GCM をおすすめしますが、さまざまなニーズに合わせてさまざまな鍵の種類があります（256 ビットのセキュリティの場合は、以下の AES128 を AES256 に置き換えてください）。原則:
- 16 バイトの初期化ベクトル（IV）を使用する AES128_CTR_HMAC_SHA256 は、適切な境界を持つ最も保守的なモードです。
- AES128_EAX は AES128_CTR_HMAC_SHA256 よりも保守的ではなく、わずかに高速です。
- 通常、AES128_GCM は最も高速なモードであり、メッセージの数とメッセージ サイズに厳しい制限があります。平文と関連するデータ長（以下）のこれらの上限を超えると、AES128_GCM が失敗し、鍵マテリアルが漏洩します。
- AES128_GCM_SIV は AES128_GCM とほぼ同じ速度です。メッセージ数とメッセージ サイズには AES128_GCM と同じ上限がありますが、これらの上限を超えても、致命的なエラーは発生しません。2 つのメッセージが同じであるという事実が漏洩するだけです。これにより、AES128_GCM よりも安全に使用できますが、実際には広く使用されていません。Java でこれを使用するには、Conscrypt をインストールする必要があります。
- XChaCha20Poly1305 では、メッセージ数とメッセージサイズの上限が AES128_GCM よりもはるかに大きいですが、失敗した場合（非常に低い確率ですが）、鍵マテリアルも漏洩します。ハードウェア アクセラレーションが使用できないため、ハードウェア アクセラレーションが使用可能な状況では AES モードよりも遅くなることがあります。
セキュリティ保証
AEAD 実装は次の機能を提供します。
- CCA2 セキュリティ。
- 80 ビット以上の認証強度。
- 合計 250 バイトの 232 個以上のメッセージを暗号化できる。最大 232 個の平文または暗号文を選択する攻撃で、成功確率が 2-32 を超えることはありません。