PKCS #11 秘密鍵暗号化解除 (CSFPSKD および CSFPSKD6)

非暗号化対称鍵を使用してデータを復号するには、PKCS #11 秘密鍵暗号化解除呼び出し可能サービスを使用します。AES、DES、BLOWFISH、および RC4 がサポートされています。このサービスは、CBC、CTR、ECB、Galois/Counter、およびストリーム・モードと PKCS #7 埋め込みをサポートします。鍵ハンドルは、PKCS #11 秘密鍵オブジェクトのハンドルである必要があります。 CKA_DECRYPT 属性は true でなければなりません。

出力フィールドの長さが短すぎて出力を保持できない場合、サービスは失敗して、出力フィールドの必要な長さを clear_text_length パラメーターに返します。

呼び出し可能サービスは、AMODE(24)、AMODE(31)、または AMODE(64) で呼び出すことができます。64 ビットの呼び出し側は CSFPSKD6 を使用する必要があります。

親トピック: PKCS #11 トークンおよびオブジェクトの使用

形式

CALL CSFPSKD(	
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_handle,
             initialization_vector_length,
             initialization_vector,
             chain_data_length,
             chain_data,
             cipher_text_length,
             cipher_text,
             cipher_text_id,
             clear_text_length,
             clear_text,
             clear_text_id)

パラメーター

return_code
方向 タイプ
出力 整数

戻りコードは、呼び出し可能サービスの一般的な結果を示しています。 ICSF および暗号化コプロセッサーの戻りコードおよび理由コードに、戻りコードがリストされています。

reason_code
方向 タイプ
出力 整数

理由コードは、アプリケーション・プログラムに返される、呼び出し可能サービスの結果を示しています。 戻りコードにはそれぞれ、特定の処理問題を示すさまざまな理由コードがあります。 ICSF および暗号化コプロセッサーの戻りコードおよび理由コード に、理由コードがリストされています。

exit_data_length
方向 タイプ
無視される 整数

このフィールドは無視されます。 このパラメーターには 0 を指定することをお勧めします。

exit_data
方向 タイプ
無視される ストリング

このフィールドは無視されます。

rule_array_count
方向 タイプ
入力 整数
rule_array パラメーターで指定するキーワードの数。 値は 0、1、2、または 3 でなければなりません。
rule_array
方向 タイプ
入力 ストリング
制御情報を呼び出し可能サービスに提供するキーワード。
表 1. 秘密鍵暗号化解除のキーワード
キーワード 意味
暗号化メカニズム (オプション。デフォルトなし。指定されない場合、メカニズムは秘密鍵の鍵タイプから取得されます。指定された場合、鍵タイプと一致する必要があります)
AES AES アルゴリズムが使用されます。
DES DES アルゴリズムが使用されます。これは単一鍵暗号化に限定されます。
DES3 DES3 アルゴリズムが使用され、これは 2 倍長および 3 倍長の鍵の暗号化を含みます。
BLOWFISH BLOWFISH アルゴリズムが使用されます。
RC4 RC4 アルゴリズムが使用されます。これはストリーム暗号です。
処理規則 (オプション)
CBC 暗号化ブロック・チェーンを実行します。暗号化テキストの長さは指定されたアルゴリズムのブロック・サイズの倍数でなければなりません (DES、DES3、および BLOWFISH の場合は 8 バイト、AES の場合は 16 バイト)。CBC は、DES、DES3、AES、および BLOWFISH についてのデフォルト値です。RC4 に対して CBC を指定することはできません。
CBC-PAD 暗号化ブロック・チェーンを実行します。暗号化テキストの長さはゼロより大きく、指定されたアルゴリズムのブロック・サイズの倍数でなければなりません。FINAL および ONLY の呼び出しの場合、PKCS #7 埋め込みが行われます。このため、非暗号化テキストは常に暗号化テキストよりも短く、長さがゼロであることもあります。BLOWFISH または RC4 に対して CBC-PAD を指定することはできません。
CTR カウンター・モード暗号化解除を実行します。暗号化テキストの長さはゼロより大きくなければなりません。非暗号化テキストは暗号化テキストと同じ長さになります。CTR は AES に対してのみ指定できます。
ECB 電子コード・ブック暗号化を実行します。暗号化テキストの長さは、指定されたアルゴリズムのブロック・サイズの倍数でなければなりません。BLOWFISH および RC4 に対して ECB を指定することはできません。
GCM Galois/Counter モード暗号化を実行します。暗号化テキストの長さはゼロより大きくなければなりません。非暗号化テキストは暗号化テキストよりも短く、認証タグの切り捨てのために長さがゼロであることもあります。GCM は AES でのみ指定できます。GMAC は、非暗号化テキストが返されない GCM の特殊な形式です。
STREAM ストリーム暗号を行います。BLOWFISH、DES、DES3、または AES に対して STREAM を指定することはできません。STREAM は RC4 のデフォルト値です。
チェーニング選択 (オプション)
INITIAL これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける最初の呼び出しであることを指定します。 暗号化ブロック・チェーンの場合、初期設定ベクトルは initialization_vector パラメーターから取得されます。処理規則 ECB または GCM とともに指定することはできません。
CONTINUE これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける中間の呼び出しであることを指定します。 中間結果は chain_data フィールドから読み取られてこのフィールドに保管されます。 処理規則 ECB または GCM とともに指定することはできません。
FINAL これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける最後の呼び出しであることを指定します。中間結果は chain_data フィールドから読み取られます。 処理規則 ECB または GCM とともに指定することはできません。
ONLY これは、当該呼び出しが唯一の呼び出しでありチェーニングされていないことを指定します。 暗号化ブロック・チェーンの場合、初期設定ベクトルは initialization_vector パラメーターから取得されます。カウンター・モードおよび Galois Counter モードの場合、初期設定パラメーターは initialization_vector パラメーターから取得されます。ONLY がデフォルトのチェーニングです。
key_handle
方向 タイプ
入力 ストリング
秘密鍵オブジェクトの 44 バイトのハンドル。key_handle のフォーマットについては ハンドルを参照してください。
initialization_vector_length
方向 タイプ
入力 整数
initialization_vector の長さ (バイト)。CBC および CBC-PAD の場合、これは DES および BLOWFISH については 8 バイトで、AES については 16 バイトでなければなりません。CTR の場合、これは initialization_vector パラメーターに記載されている構造のサイズ (17 バイト) でなければなりません。 GCM の場合、これは initialization_vector フィールドのサイズ (28 バイト) でなければなりません。
initialization_vector
方向 タイプ
入力 ストリング
このフィールドのフォーマットは指定されるメカニズムによって変化します。CBC および CBC-PAD の場合、これは 8 または 16 バイトの初期チェーン値です。GCM および CTR のフォーマットを以下の表に示します。
表 2. GCM メカニズムについての initialization_vector パラメーター・フォーマット
オフセット 長さ (バイト) 方向 説明
0 4 入力 初期設定ベクトルのバイト単位の長さ。 最小値は 1、最大値は 128 です。 12 が推奨値です。
4 8 入力 初期設定ベクトルの 64 ビット・アドレス。 データは呼び出し側のアドレス・スペースに存在しなければなりません。高位ワードは AMODE31 呼び出し側によってすべてゼロに設定される必要があります。
12 4 入力 追加認証データのバイト単位の長さ。最小値は 0、最大値は 1048576 です。
16 8 入力 追加認証データの 64 ビット・アドレス。データは呼び出し側のアドレス・スペースに存在しなければなりません。高位ワードは AMODE31 呼び出し側によってすべてゼロに設定される必要があります。 このフィールドは、追加認証データの長さがゼロの場合に無視されます。
24 4 入力 必要な認証タグのバイト単位の長さ。 この値は 4、8、12、13、14、15、または 16 のいずれかでなければなりません。
表 3. CTR メカニズムについての initialization_vector パラメーター・フォーマット
オフセット 長さ (バイト) 方向 説明
0 16 入力 初期カウンター・ブロック。
16 1 入力 増分されるカウンターの低位のバイト数。残りの上位バイトは nonce です。 有効な値は 1 からブロック・サイズまでで、両端の値を含みます。ブロック・サイズは AES については 16 です。
chain_data_length
方向 タイプ
入出力 整数
chain_data パラメーターのバイト長。この値は 128 バイトでなければなりません。
chain_data
方向 タイプ
入出力 ストリング
このフィールドは 128 バイトの作業域です。 チェーン・データでは、ある呼び出しから別の呼び出しへのデータのチェーニングが許可されます。ICSF は INITIAL 呼び出しでチェーン・データを初期化し、後続の CONTINUE 呼び出しでこれを変更できます。ご使用のアプリケーションで、特定のメッセージに対する一連の INITIAL、CONTINUE、および FINAL 呼び出しの間に、このフィールドに含まれるデータを変更してはなりません。 チェーン・データのフォーマットは以下の通りです。
表 4. chain_data パラメーター・フォーマット
オフセット 長さ 説明
0 4 フラグ・ワード
ビット
オンに設定されたときの意味
0
暗号状態オブジェクトが割り振られています
1-31
IBM で使用するために予約済み
4 44 暗号状態オブジェクト・ハンドル
48 80 IBM で使用するために予約済み
cipher_text_length
方向 タイプ
入力 整数
cipher_text パラメーターの長さ (バイト)。処理規則 GCM を除き、長さは最大 2147483647 まで可能です。処理規則 GCM の場合、長さは 1048576 にタグの長さを加えたものを超えてはなりません。
cipher_text
方向 タイプ
入力 ストリング
暗号化解除されるテキスト。
cipher_text_id
方向 タイプ
入力 整数
暗号化テキストが存在するスペースを識別する ALET。
clear_text_length
方向 タイプ
入出力 整数
入力では、clear_text パラメーターの長さ (バイト)。出力では、clear_text パラメーターに暗号化解除されるテキストの長さ。
clear_text
方向 タイプ
出力 ストリング
暗号化解除されるテキスト
clear_text_id
方向 タイプ
入力 整数
非暗号化テキストが存在するスペースを識別する ALET。

許可

このサービスを共通オブジェクトとともに使用するには、呼び出し側は少なくとも SO (READ) 権限または USER (READ) 権限 (任意のアクセス) を持つ必要があります。

このサービスを秘密オブジェクトとともに使用するには、呼び出し側は少なくとも USER (READ) 権限 (ユーザー・アクセス) を持つ必要があります。

使用上の注意

チェーニングされた一連の呼び出しを開始するために INITIAL 規則が使用される場合、以下のようになります。
  • 同一の key_handle、暗号化メカニズム、および処理規則を後続の CONTINUE および FINAL 呼び出しで使用する必要があります。
  • チェーニングされた呼び出しを開始するために使用する鍵は、チェーニングされた呼び出しが完了するまで削除してはなりません。
  • アプリケーションは、割り振られた ICSF リソースを解放するために FINAL 呼び出しを行う必要があります。FINAL 呼び出しを行わずに処理が中止され、暗号状態オブジェクトが割り当てられたことが chain_data パラメーターによって示される場合、呼び出し側は、状態オブジェクトのハンドルを渡す CSFPTRD (あるいは 64 ビットの呼び出し側の場合は CSFPTRD6) を呼び出すことによってオブジェクトを解放する必要があります。

GCM 暗号化解除を使用して、一部の認証データの GMAC を検証することができます。これを行うには、処理規則を使用して AES 暗号化解除を要求します。cipher_text_length および cipher_text フィールドを、検証する GMAC の長さと値に設定する必要があります。return_code がゼロで、clear_text データが返されない場合、GMAC 検証に成功したことを意味します。

処理規則 CTR または GCM にはセキュア鍵を使用できません。