プレーンテキストを暗号化して暗号文にします。
操作の説明
Key Management Service (KMS) は、Encrypt と AdvanceEncrypt の 2 つの暗号化 API を提供します。主な違いは、使用するキーバージョンと、その後に呼び出す必要がある復号 API です。
| Encrypt | AdvanceEncrypt | |
|---|---|---|
| 使用するキーバージョン | 初期バージョン | プライマリバージョン |
| 互換性のある復号 API | Decrypt または AdvanceDecrypt | AdvanceDecrypt のみ |
ソフトウェアキー管理インスタンスで対称キーを使用し、そのソフトウェアで保護されたキーに対してキーローテーションが有効になっている場合、Encrypt の代わりに AdvanceEncrypt を呼び出してください。そうしないと、キーローテーション機能は有効になりません。詳細については、「キーローテーションの設定」をご参照ください。
キーの仕様、暗号化モード、秘密キーの暗号化、キーバージョンの詳細については、「キーのタイプと仕様」をご参照ください。
注意事項
すべてのリクエストパラメーターは Protocol Buffers でエンコードされます。生成されるリクエスト本文は 3 MB を超えることはできません。データ量が 3 MB を超えると、サーバーはリクエストを拒否し、HTTP ステータスコード 413 を返します。
1 回の暗号化または復号の呼び出しでは、データを次の制限内に収めてください：
キータイプ | 推奨最大データ量 |
対称キー | 6 KB |
非対称キー | 1 KB |
データがこれらの制限を超える場合は、代わりにエンベロープ暗号化を使用してください。詳細については、「エンベロープ暗号化」をご参照ください。
1 回の呼び出しのデータ量が大きいほど、ネットワーク伝送障害のリスクが高まり、伝送に時間がかかり、KMS インスタンスがデータの暗号化または復号を完了するのに必要な時間も長くなります。
リクエストパラメーター
| パラメーター | タイプ | 必須 | 例 | 説明 |
|---|---|---|---|---|
| KeyId | 文字列 | はい | key-hzz62f1cb66fa42qo**** | キーのグローバル一意識別子です。キーに紐付けられたエイリアスを指定することもできます。 |
| Plaintext | バイト | はい | バイナリデータ | 暗号化するプレーンテキストです。 |
| Algorithm | 文字列 | いいえ | AES_GCM | 暗号化アルゴリズムです。指定しない場合、KMS はキーのデフォルトアルゴリズムを使用します。詳細については、「キーのタイプと仕様」をご参照ください。 |
| Iv | バイト | いいえ | バイナリデータ | データ暗号化に使用する初期化ベクトル (IV) です。暗号化アルゴリズム (Algorithm) が AES_GCM、AES_CBC の場合にのみ有効です。有効な長さ：Algorithm が AES_CBC の場合は 16 バイト、Algorithm が AES_GCM の場合は 12 バイトです。指定しない場合、KMS はランダムな値を生成します。このパラメーターは設定せず、KMS にランダムに生成させることを推奨します。 |
| Aad | バイナリ | いいえ | バイナリデータ | データ暗号化時の GCM モード認証に使用する追加認証データ (AAD) です。キーが対称キーで、暗号化アルゴリズム (Algorithm) が AES_GCM または SM4_GCM の場合に、このパラメーターを設定できます。このパラメーターを設定した場合、Decrypt を呼び出して暗号化されたデータを復号する際に、同じ値を渡す必要があります。 |
| PaddingMode | 文字列 | いいえ | PKCS7_PADDING | パディングモードです。Algorithm が AES_CBC または AES_ECB に設定されている場合にのみ必須です。有効な値：PKCS7_PADDING (デフォルト) および NO_PADDING。 |
PaddingMode の値
PKCS7_PADDING(デフォルト)：PKCS#7 パディングを使用します。入力が L バイトの場合、KMS は K − (L mod K) バイトのパディングを追加します。ここで、K は暗号ブロックサイズです。NO_PADDING：パディングは追加されません。プレーンテキストの長さは、暗号ブロックサイズの整数倍である必要があります。
レスポンス要素
| パラメーター | タイプ | 例 | 説明 |
|---|---|---|---|
| Iv | バイト | バイナリデータ | データ暗号化に使用した初期化ベクトル (IV) です。暗号化アルゴリズム (Algorithm) が AES_GCM、AES_CBC の場合にのみ有効な値が返されます。それ以外の場合は空になります。 |
| CiphertextBlob | バイト | バイナリデータ | 指定されたキーで暗号化された後のデータの暗号文 BLOB です。 注：楕円曲線統合暗号化方式 (ECIES) アルゴリズムを使用する場合、返される暗号文の形式は SEC 1: Elliptic Curve Cryptography, Version 2.0 標準に準拠します。 |
| KeyId | 文字列 | key-hzz62f1cb66fa42qo**** | キーのグローバル一意識別子です。KeyId リクエストパラメーターでキーのエイリアスを指定した場合、このレスポンス要素は、そのエイリアスに紐付けられているキーのグローバル一意識別子を返します。 |
| Algorithm | 文字列 | AES_GCM | 暗号化アルゴリズムです。 |
| PaddingMode | 文字列 | PKCS7_PADDING | パディングモードです。Algorithm が AES_CBC または AES_ECB の場合にのみ値が返されます。それ以外の場合は空になります。 |
| RequestId | 文字列 | 475f1620-b9d3-4d35-b5c6-3fbdd941423d | リクエストの ID です。Alibaba Cloud は、リクエストごとにこの一意の識別子を生成します。これを使用して、問題のトラブルシューティングや特定を行うことができます。 |
エラーコード
エラーコードの一覧については、「サービスエラーコード」をご参照ください。