保管鍵リスト (CSNDRKL および CSNFRKL)

CALL CSNDRKL(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_label_mask,
             retained_keys_count,
             key_labels_count,
             key_labels)

return_code

方向	タイプ
出力	整数

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

reason_code

方向	タイプ
出力	整数

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

exit_data_length

方向	タイプ
入出力	整数

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

exit_data

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

インストール・システム出口に渡されるデータ。

rule_array_count

方向	タイプ
入力	整数

rule_array パラメーターで指定されているキーワード数。 値は 0 でなければなりません。

rule_array

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

このパラメーターは ICSF では無視されます。

key_label_mask

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

verb によって返された鍵名のリストをフィルターに掛けるために使用する、64 バイトの鍵ラベル・マスク。 ワイルドカード (*) を使用して、コプロセッサー内に保存された複数の鍵を指定できます。

注: アスタリスク (*) を使用する場合、これは key_label_mask 内の最後の文字でなければなりません。 使用可能な * は 1 つのみです。

retained_keys_count

方向	タイプ
出力	整数

すべてのアクティブ・コプロセッサー内に保存された保管鍵の数を受け取る整変数。

key_labels_count

方向	タイプ
入出力	整数

入力の場合、この変数は、返される鍵ラベルの最大数を定義します。 出力の場合、この変数は、返される鍵ラベルの総数を定義します。 このフィールドの最大値は 100 です。 返される十分な数の鍵ラベルを key_labels_count フィールドに指定しなかった場合は、retained_keys_count 変数で返される値が大きくなる可能性があります。

key_labels

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

鍵ラベル情報が返されるストリング変数。 このフィールドは、鍵ラベル・カウント値の少なくとも 64 倍でなければなりません。 鍵ラベル情報は、ゼロのストリングまたは 64 バイトを超える項目です。 最初の 64 バイトの項目にはコプロセッサー・シリアル番号が含まれ、その後に、そのコプロセッサー内に保存されている鍵の鍵ラベルをそれぞれ含む 1 つ以上の 64 バイト項目が続きます。 最初の 64 バイト項目のフォーマットは以下のとおりです。

 /nnnnnnnnbbbbb...bbb
where
 "/" is the character "/" (EBCDIC: X'61')
 "nnnnnnnn" is the 8-byte cryptographic coprocessor serial number
 "bbbbb...bbb" is 55 bytes of blank pad characters
   (EBCDIC: X'40')

この情報 (64 バイトのカード・シリアル番号項目とそれに続く 1 つ以上の 64 バイトのラベル項目) は、key_label_mask に一致する保管鍵を含む、アクティブ・コプロセッサーごとに繰り返されます。 返されるデータはすべて EBCDIC 文字です。 返される情報のバイト数は、key_labels_count フィールドに指定された値によって決まります。 key_labels フィールドは、key_labels_count フィールドに指定された数の 64 バイト・ラベルに加えて、アクティブ・コプロセッサー (最大 64 個のコプロセッサー) ごとに 1 つの 64 バイト項目を保持するために十分な大きさでなければなりません。

複数のコプロセッサーをサポートしていないプラットフォームもあります。 1 つのカードのみがサポートされている場合、key_labels フィールドには、コプロセッサー内に保存されている鍵の鍵ラベルをそれぞれ含む、1 つ以上の 64 バイト項目が入れられます。 64 バイト項目には、コプロセッサー・シリアル番号は入れられません。

ICSF は RACF を呼び出して、保管鍵リストサービスの使用許可を検査します。

ICSF 呼び出し側は、* を含む key_label_mask 名に対して許可されている必要があります。

保管秘密鍵はドメイン固有です。 ICSF は、保管鍵リスト要求の発行元である LPAR ドメインによって作成された鍵のみをリストします。

「Retained Key List」アクセス制御点によって、このサービスの機能が制御されます。

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