リモート鍵エクスポート (CSNDRKX および CSNFRKX)

CALL CSNDRKX(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             trusted_block_length,
             trusted_block_identifier,
             certificate_length,
             certificate,
             certificate_parms_length,
             certificate_parms,
             transport_key_length,
             transport_key_identifier,
             rule_id_length,
             rule_id,
             importer_key_length,
             importer_key_identifier,
             source_key_length,
             source_key_identifier,
             asym_encrypted_key_length,
             asym_encrypted_key,
             sym_encrypted_key_length,
             sym_encrypted_key,
             extra_data_length,
             extra_data,
             key_check_parameters_length,
             key_check_parameters,
             key_check_length,
             key_check_value)

return_code

方向	タイプ
出力	整数

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

reason_code

方向	タイプ
出力	整数

理由コードは具体的な処理結果を示します。 戻りコードにはそれぞれ、特定の処理問題を示すさまざまな理由コードがあります。 ICSF および暗号化コプロセッサーの戻りコードおよび理由コード に、理由コードがリストされています。

exit_data_length

方向	タイプ
入出力	整数

インストール・システム出口に渡されるデータの長さ。 データは exit_data パラメーターで識別されます。

exit_data

方向	タイプ
入出力	ストリング

このデータはインストール出口に渡されます。

rule_array_count

方向	タイプ
入力	整数

rule_array パラメーターで指定するキーワード数。 この番号は 0、1、または 2 でなければなりません。

rule_array

方向	タイプ
入力	文字ストリング

rule_array パラメーターはキーワードの配列です。 キーワードは、8 バイトの連続するストレージ内になければならず、その 8 バイト位置で左寄せされ、右側にブランクが埋め込まれている必要があります。 rule_array キーワードは以下のとおりです。

表 1. rule_array keywords

キーワード	意味
鍵ラップ方式 (オプション)
USECONFG	デフォルト・ラップ方式の構成設定を鍵のラップに使用することを指定します。 これはデフォルトです。
WRAP-ENH	新しい拡張ラップ方式を鍵のラップに使用することを指定します。
WRAP-ECB	元のラップ方式を使用することを指定します。
変換制御 (オプション。拡張ラップに対してのみ有効)
ENH-ONLY	このキーワードは、拡張方式でいったんラップされた鍵を元の方式でラップできないように指示する場合に指定します。 これにより、元の方式への変換が制限されます。

trusted_block_length

方向	タイプ
入力	整数

これは、trusted_block_identifier パラメーターでのバイトの数を指定します。 最大長は 3500 バイトです。

trusted_block_identifier

方向	タイプ
入力	ストリング

これは、 このサービスで構成される内部/完全トラステッド・ブロックのトラステッド・ブロック・ラベルまたはトラステッド・ブロック・トークンを指定します。 これは、公開鍵証明書 (証明書) を検証し、鍵を生成およびエクスポートするための規則を定義するために使用されます。

certificate_length

方向	タイプ
入力	整数

これは、証明書パラメーターでのバイトの数を指定します。 最大値は 5000 バイトです。

certificate_length がゼロのときに、トラステッド・ブロックの非対称暗号化出力鍵フォーマットが非対称鍵出力を示していない場合、 このサービスでは、証明書を使用したり検証したりすることは決して試みられません。 そのため、出力パラメーター asym_encrypted_key_length にはゼロが含まれ、出力パラメーター asym_encrypted_key は入力内容からは変更されません。

証明書の長さがゼロのときに、 トラステッド・ブロックの非対称暗号化出力鍵フォーマットが PKCS1.2 出力フォーマットや RSAOAEP 出力フォーマットを示している場合、 このサービスはエラーで終了します。

certificate_length がゼロ以外のときに、トラステッド・ブロックの非対称暗号化出力鍵フォーマットが非対称鍵出力を示していない場合、 このサービスは失敗します。

certificate

方向	タイプ
入力	ストリング

公開鍵証明書が含まれます。 その証明書には、デジタル署名が含まれているだけでなく、公開鍵のモジュラスと指数も binary_form で含まれていなければなりません。 証明書の署名は、trusted_block_identifier パラメーターで指定されているトラステッド・ブロックに含まれるルート公開鍵を使用して検証されます。

certificate_parms_length

方向	タイプ
入力	整数

certificate_parms パラメーターでのバイトの数が含まれます。 長さは 36 バイトでなければなりません。

certificate_parms

方向	タイプ
入力	ストリング

呼び出し側によって指定された構造が含まれます。 この構造は、パラメーター証明書において証明書内の値の位置と長さを識別するために使用されます。 この構造には、RKX で使用される値ごとに、証明書の先頭からのオフセットと、長さ (バイト) が含まれます。 その値は、呼び出し側のアプリケーション・プログラムが指定します。 この方式では、各種証明書フォーマットが非常に柔軟にサポートされます。 構造のレイアウトは、以下のとおりです。

表 2. RKX で使用される値の構造

オフセット (バイト)	長さ (バイト)	説明
0	4	モジュラスのオフセット
4	4	モジュラスの長さ
8	4	公開鍵指数のオフセット
12	4	公開鍵指数の長さ
16	4	デジタル署名のオフセット
20	4	デジタル署名の長さ
24	1	使用されるハッシュ・アルゴリズムの ID
25	1	デジタル・ハッシュ・フォーマット方式の ID 01 - PKCS-1.0 02 - PKCS-1.1 03 - X9.31 04 - ISO-9796 05 - ZERO-PAD
26	2	予約済み - 0x00 バイトで埋める必要があります
28	4	デジタル署名を計算するためにハッシュされる証明書データの先頭バイトのオフセット
32	4	デジタル署名を計算するためにハッシュされる証明書データの長さ

モジュラス値、指数値、および署名値は右寄せにされ、必要に応じて左側に 2 進ゼロが埋め込まれます。

これらの値は、構造内のオフセット 24 の位置でハッシュ・アルゴリズム ID に対して定義されます。

表 3. リモート鍵エクスポート用に構造内のオフセット 24 の位置でハッシュ・アルゴリズム ID に対して定義される値

ID	アルゴリズム
0X01	SHA-1
0X02	MD5
0X03	RIPEMD-160

transport_key_length

方向	タイプ
入力	整数

transport_key_identifier パラメーターでのバイトの数が含まれます。

transport_key_identifier

方向	タイプ
入力	ストリング

内部鍵トークンのラベルが含まれるか、 または RKX サービスによってエクスポートされる鍵を暗号化するために使用される鍵暗号化鍵 (KEK) の RKX トークンのラベルが含まれます。 トランスポート鍵は、生成対象鍵を暗号化するためには使用されません。

規則セクション内のフラグ bit0 が 1 (既存の鍵をエクスポート) であり、 パラメーター rule_id が規則セクション ruleID である場合、パラメーター source_key_identifier で受け取られた鍵の エクスポート・バージョンが transport_key_identifier によって暗号化されます。 このサービスでは、以下のように、鍵トークンに含まれているオフセット 0x04 の位置のバージョン番号と、 オフセット 0x00 の位置のフラグ値によって、内部鍵トークンと RKX 鍵トークンを区別できます。

表 4. RKX で使用される Transport_key_identifer

フラグ・バイト・オフセット 00	バージョン番号オフセット 04	説明
0X01	0X00	内部 DES 鍵トークン・バージョン 0
0X02	0X10	RKX 鍵トークン (フラグ・バイト 0x02 は外部鍵トークンを示します)

rule_id_length

方向	タイプ
入力	整数

rule_id パラメーターでのバイトの数が含まれます。 値は 8 でなければなりません。

rule_id

方向	タイプ
入力	ストリング

これは、鍵の生成/エクスポートを制御するために 使用される規則をトラステッド・ブロックにおいて指定します。 トラステッド・ブロックには複数の規則を含めることができます。 各規則は規則 ID 値によって識別されます。

importer_key_length

方向	タイプ
入力	整数

importer_key_identifier パラメーターでのバイトの数が含まれます。 これは、トラステッド・ブロック規則セクション (セクション 0x12) の生成/エクスポート・フラグがゼロの場合はゼロでなければなりません。 この場合は、新規の鍵が生成されます。

importer_key_identifier

方向	タイプ
入力	ストリング

パラメーター source_key_identifier で渡された 鍵を復号するために使用される IMPORTER 鍵暗号鍵の鍵トークンまたは鍵ラベルが含まれます。 これは、鍵を生成するために RKX 鍵が使用されている場合や、source_key_identifier が RKX 鍵トークンまたは内部 DES 鍵トークンである場合は使用されません。

source_key_length

方向	タイプ
入力	整数

source_key_identifier パラメーターでのバイトの数が含まれます。 このパラメーターは、トラステッド・ブロック規則セクションの ruleID が rule_id パラメーターであり、 フラグ bit0 が 0 (新規の鍵を生成) である場合は 0 でなければなりません。

このパラメーターは、トラステッド・ブロック規則セクションのフラグ bit0 が 1 (既存の鍵をエクスポート) の場合は 64 でなければなりません。

source_key_identifier

方向	タイプ
入力	ストリング

エクスポート対象の鍵の単一長/倍長の外部/内部鍵トークン または RKX 鍵トークンのラベルが含まれます。 これは、新規の鍵を生成するために RKX が使用される場合は空 (source_key_length=0) でなければなりません。 このサービスでは、指定されている形式を判別するために鍵トークンが使用されます。

表 5. source_key_identifier の鍵トークンの検査

フラグ・バイト・オフセット 00	バージョン番号オフセット 04	説明
0X01	0X00	内部 DES 鍵トークン・バージョン 0
0X02	0X00	外部 DES 鍵トークン・バージョン 0
0X02	0X01	外部 DES 鍵トークン・バージョン 1
0X02	0X10	RKX 鍵トークン (フラグ・バイト 0x02 は外部鍵トークンを示します)

asym_encrypted_key_length

方向	タイプ
入出力	整数

asym_encrypted_key パラメーターの長さ。 入力では、これは出力を受け取るためのストレージの長さです。 出力では、これは asym_encrypted_key パラメーターで返されるデータの長さです。 最大長は 512 バイトです。

asym_encrypted_key

方向	タイプ
出力	ストリング

このフィールドの内容は入力では無視されます。 これは、生成/エクスポートされた鍵を、パラメーター証明書で渡される公開 (非対称) 鍵で暗号化された状態で 返すために RKX で使用されるストリング・バッファーです。 呼び出し側のバッファーが小さすぎて、返される値を保持できない場合は、エラーが返されます。

sym_encrypted_key_length

方向	タイプ
入出力	整数

入力では、sym_encrypted_key_length パラメーターは、sym_encrypted_key フィールドでのバイトの数が含まれる整変数です。 出力では、sym_encrypted_key_length の値は、sym_encrypted_key フィールドで返される鍵の長さで置き換えられます。

sym_encrypted_key

方向	タイプ
出力	ストリング

sym_encrypted_key は、 生成/エクスポートされた鍵を、transport_key_identifier パラメーターで渡される鍵暗号鍵で暗号化された状態で 返すために RKX で使用されるストリング・バッファーです。 返される値は 64 バイトでなければなりません。 呼び出し側のバッファーが 64 バイトより小さいために、返される値を保持できない場合は、エラーが返されます。 sym_encrypted_key は、trusted_block_identifier パラメーター内の規則セクションの対称暗号化出力鍵フォーマットの値に応じて RKX 鍵トークン または鍵トークンになる可能性があります。

ICSF は、対称鍵トークンにおいて鍵値をラップする方式として、元の ECB ラップ方式と、ANSI X9.24 準拠の拡張 CBC ラップ方式の 2 つの方式をサポートします。 sym_encrypted_key は、source_key_identifier と同じ方法でラップされます。

extra_data_length

方向	タイプ
入力	整数

extra_data パラメーターでのデータのバイト数が含まれます。 これは、asym_encrypted_key での RSA 暗号化鍵の出力フォーマットが RSAOEAP 以外の場合はゼロでなければなりません。 最大サイズは 1024 バイトです。

extra_data

方向	タイプ
入力	ストリング

これは OAEP 鍵ラップ処理で使用できます。 extra_data はオプションです。 これは、asym_encrypted_key で返される RSA 暗号化鍵の出力フォーマットが RSAOAEP の場合にのみ適用できます。

注: RSAOAEP フォーマットは、トラステッド・ブロック内の規則に指定されます。

key_check_parameters_length

方向	タイプ
入力	整数

key_check_parameters パラメーターでのバイトの数が含まれます。 現時点では、鍵検査パラメーターを必要とする定義済みの鍵検査アルゴリズムはないため、このフィールドには 0 を指定する必要があります。

key_check_parameters

方向	タイプ
入力	ストリング

鍵検査値パラメーターを計算するために必要となるパラメーターが含まれます。 そのパラメーターは、key_check_value で返されます。 現時点では、鍵検査パラメーターを必要とする定義済みの鍵検査アルゴリズムはありませんが、このパラメーターは指定する必要があります。

key_check_length

方向	タイプ
入出力	整数

入力では、 このパラメーターには key_check_value パラメーターでのバイトの数が含まれます。 出力では、この値は key_check_value パラメーターで返される鍵検査値の長さで置き換えられます。 その長さは、鍵検査アルゴリズム ID によって異なります。 表 1を参照してください。

key_check_value

方向	タイプ
出力	ストリング

これは、 生成/エクスポートされた鍵に対して計算される鍵検査値を返すために RKX で使用されます。 rule_id で指定される規則内の値により、この出力値の計算に使用されなければならない鍵検査アルゴリズムを指定できます。

呼び出し側がこの呼び出し可能サービス、鍵ラベル、または CKDS か PKDS に保管された内部セキュア鍵トークンの使用を許可されているかを検査するために、SAF が呼び出される場合があります。

「Remote Key Export - Gen or export a non-CCA node Key」アクセス制御点では、このサービスの機能が制御されます。

リモート鍵エクスポート・サービスで NOCV IMPORTER 鍵暗号鍵を使用するには、リストされているアクセス制御点の一方または両方に 加えて、「NOCV KEK usage for import-related functions」アクセス制御点が有効になっていなければなりません。

リモート鍵エクスポート・サービスで NOCV EXPORTER 鍵暗号鍵を使用するには、リストされているアクセス制御点の一方または両方に 加えて、「NOCV KEK usage for export-related functions」アクセス制御点が有効になっていなければなりません。

「RKX/TBC - Disallow triple-length MAC key」アクセス制御点が有効になっている場合、このサービスでは、 倍長の KEK でラップされた 3 倍長の MAC はインポートされません。

WRAP-ECB キーワードまたは WRAP-ENH キーワードを指定するときは、「Remote Key Export - Allow wrapping override keywords」アクセス制御点が 有効になっていなければなりません。

下表に、各サーバー・タイプに必要な暗号化ハードウェアを示し、この呼び出し可能サービスの制約事項について説明します。