鍵データ・セット・リスト (CSFKDSL および CSFKDSL6)

CKDS および PKDS ラベルまたは TKDS オブジェクト処理のリストまたはカウントを生成するには、鍵データ・セット・リスト呼び出し可能サービスを使用します。リストはメタデータについての検索基準によって詳細化できます。

鍵データ・セットの KDSR フォーマット (HCR77A1 で導入) には検索基準として使用できるメタデータが含まれています。古い鍵データ・セット・フォーマットでは、レコードの作成日および更新日のみが利用できます。鍵データ・セットのフォーマットによってサポートされていないメタデータが検索基準に含まれている場合、サービスは戻りコード 4 を戻し、リストまたはカウントを生成しません。鍵データ・セットを KDSR フォーマットに変換するには、調整 KDS 管理呼び出し可能サービス (CSFCRC および CSFCRC6)を参照してください。

CKDS および PKDS の場合、ラベルは最大 64 バイト長の文字ストリングです。ラベルのフィルターにワイルドカードを使用できます。情報については、『使用上の注意』を参照してください。検索基準は、ラベル・フィルターに一致するレコードに適用されます。

TKDS の場合、名前は 32 バイトのトークン名です。ワイルドカードは許可されません。検索基準は、指定されるトークンのオブジェクトに適用されます。PKCS #11 オブジェクトのみメタデータがあることに注意してください。トークンは TKDS 内にレコードを持ちますが、メタデータがありません。

TKDS 内のトークンはこのサービスを使用してリストすることはできません。トークンのリストを生成するにはトークン・レコード・リスト・サービスが使用されます。

AMODE(64) の呼び出し可能サービス名は CSFKDSL6 です。

形式

CALL CSFKDSL (
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             label_filter_length,
             label_filter,
             search_criteria_length,
             search_criteria,
             label_count,
             output_list_length,
             output_list,
             reserved1_length,
             reserved1,
             reserved2_length,
             reserved2,
             continuation_area)

パラメーター

return_code

方向	タイプ
出力	整数

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

reason_code

方向	タイプ
出力	整数

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

exit_data_length

方向	タイプ
入出力	整数

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

exit_data

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

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

rule_array_count

方向	タイプ
入力	整数

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

rule_array

方向	タイプ
入力	文字

rule_array パラメーターには、呼び出し可能サービスに制御情報を提供するキーワードが含まれています。キーワードは、連続するストレージ内になければならず、各キーワードはその 8 バイト位置で左寄せされ、右側にブランクが埋め込まれている必要があります。

表 1. KDS リスト制御情報のキーワード
キーワード	意味
鍵データ・セット (必須)
CKDS	アクティブな CKDS が検索されることを指定します。
PKDS	アクティブな PKDS が検索されることを指定します。
TKDS	アクティブな TKDS が検索されることを指定します。
出力フォーマット (必須)
LABELS	検索基準に一致するラベルのリストが戻されることを指定します。
COUNT	検索基準に一致するラベルの数が戻されることを指定します。
レコードの状態 (必須)
ACTIVE	アーカイブされておらず、(指定された場合に) 開始日/終了日の範囲内にあるレコードのみを検査することを指定します。開始日および終了日がレコードに設定されていない場合、レコードはアクティブであると見なされます。
INACTIVE	アーカイブされておらず、開始日/終了日の範囲内にないレコードのみを検査することを指定します。
ARCHIVED	アーカイブされているレコードのみを検査することを指定します。
ALL	すべてのレコードを検査することを指定します。

label_filter_length

方向	タイプ
入力	整数

label_filter_length パラメーターは、label_filter パラメーターの長さ (バイト) を指定します。

CKDS および PKDS の場合、値はゼロから 80 の範囲にすることができます。長さがゼロの場合、フィルター操作は使用されません。

TKDS の場合、値は 32 でなければなりません。

label_filter

方向	タイプ
入力	文字

label_filter パラメーターには、ラベルまたはハンドルによる鍵データ・セット・レコードのフィルタリングに使用される情報が含まれています。

CKDS および PKDS の場合、フィルターは 64 バイトのラベル用です。ワイルドカードが許可されます。ブランク文字は許可されません。詳細については、『使用上の注意』を参照してください。

TKDS の場合、これは 32 バイトのトークン名でなければなりません。ワイルドカードは許可されません。末尾ブランクは許可されます。検索基準は、指定されるトークンのオブジェクトに適用されます。

search_criteria_length

方向	タイプ
入力	整数

search_criteria_length パラメーターは、search_criteria パラメーターの長さ (バイト) です。検索基準が適用されない場合、値はゼロになることがあります。最大値は 500 です。

search_criteria

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

search_criteria パラメーターは、検索に適用される検索基準のリストです。search_criteria は、連続するストレージ内の項目のブロックです。

各リスト項目は、追加データだけでなく、単一の検索基準を示しています。リスト内のすべての基準は、鍵データ・セットのラベル・フィルターと一致する各レコードに適用されます。このリストの各項目は、表 2 に示されている構造を使用します。

表 2. 検索基準の項目
オフセット (10 進数)	バイト数	説明
0	2	検索条件: 値意味 X'0001' 基準は日付です。 X'0002' 基準メタデータ・タグです。 X'0003' 基準は TKDS オブジェクト・タイプです。 X'0004' 基準は CKDS 鍵タイプです。 X'0005' 基準はメタデータ・フラグです。
2	2	構造の長さ。長さには検索基準およびこの長さフィールドが含まれます。
4		追加情報 (必須): 詳しくは、表 3を参照してください。メタデータ・タグについては、表 4 を参照してください。 TKDS オブジェクト・タイプについては、表 5 を参照してください。 CKDS 鍵タイプについては、表 6 を参照してください。メタデータ・フラグについては、表 7 を参照してください。

検索基準として日付を使用するには、使用する日付タイプ、比較演算子、および YYYYMMDD 形式の日付または 2 進ゼロを選択します。2 進ゼロは、日付が未設定であることを意味します。
ゼロに等しい日付を検索するとき、日付がゼロまたはメタデータ・ブロックが存在しない場合にレコードが一致します。レコードがアーカイブまたは再呼び出しされた日付がメタデータ・ブロック内に保管されます。
非ゼロの日付よりも小さいか、それ以下の日付を検索するとき、そのタイプの非ゼロの日付がレコード内に存在する場合に限りレコードが一致します。
ゼロ以下の日付の検索は、ゼロに等しい日付の要求と同様に処理されます。

表 3. 日付タグを使用した検索基準
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	1	検索基準は日付です。
2	2	14	項目の長さ。
4	1		日付タイプ: 値日付 X'01' レコードの作成日。 X'02' レコードの最終更新日。 X'03' レコードの最後参照日。 X'04' レコードがアーカイブされた日。 X'05' 鍵素材有効期間開始日。 X'06' 鍵素材有効期間終了日。 X'07' レコードが再呼び出しされた日。
5	1		日付比較: 値意味 X'01' 指定された日付より小さい日付。 X'02' 指定された日付より大きい日付。 X'03' 指定された日付と等しい日付。 X'04' 指定された日付より小さいか等しい日付。 X'05' 指定された日付より大きいか等しい日付。
6	8		YYYYMMDD 形式の日付 (EBCDIC 数字) または 2 進ゼロ。

検索基準としてメタデータ・タグを使用するには、有効なタグを選択します。

表 4. メタデータ・タグを使用した検索基準
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	2	検索基準はメタデータ・タグです。
2	2	6	項目の長さ。
4	2		メタデータ・タグ: 値意味 X'0001' インストール・システム・ユーザー・データ。 X'0002' レコードを参照したサービス。 X'0003' レコード・アーカイブ日。 X'0004' レコード再呼び出し日。 X'0005'-X'7FFF' IBM が使用するために予約済みです。 X'8000'-X'FFFF' インストール・システム・メタデータ。

TKDS オブジェクト・タイプを検索基準として使用するには、必要なオブジェクトのタイプを指定します。

表 5. TKDS オブジェクト・タイプを使用した検索基準
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	3	検索基準は TKDS オブジェクト・タイプです。
2	2	5	項目の長さ。
4	1		オブジェクト・タイプ: 値 (EBCDIC) 意味 'T' オブジェクトの鍵素材は暗号化されていません。 'Y' オブジェクトの鍵素材は EP11 マスター鍵によってラップされています。

CKDS 鍵タイプを検索基準として使用するには、必要な鍵のタイプを指定します。

表 6. CKDS 鍵タイプを使用した検索基準
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	4	検索基準は CKDS 鍵タイプです。
2	2	12	項目の長さ。
4	8		ラベルの CKDS 鍵タイプ (バイト 65-72): 値 (EBCDIC) 意味 ADATA DES ANSI X9.17 DATA 鍵。 AKEK DES ANSI X9.17 鍵暗号鍵。 CIPHER AES CIPHER 鍵。 CV 以下のいずれかの DES 鍵タイプ: CIPHER、 CIPHERXI、 CIPHERXL、 CIPHERXO、 CVARDEC、 CVARENC、 CVARPINE、 CVARXCVL、 CVARXCVR、 DATAC、 DATAM、 DATAMV、 DECIPHER、 DKYGENKY、 ENCIPHER、 IKEYXLAT、 KEYGENKY、 OKEYXLAT、 SECMSG。 DATA AES DATA 鍵および DES DATA 鍵 (暗号化および非暗号化)。 DATAXLAT DES データ変換鍵。 DKYGENKY AES DKYGENKY。 EXPORTER AES エクスポーター鍵および DES エクスポーター鍵。 IMPORTER AES および DES インポーター鍵。 IMP-PKA DES 制限権限インポーター鍵。 IPINENC DES 入力 PIN 暗号化鍵。 MAC AES 鍵、DES 鍵、および HMAC MAC 鍵。 MACD DES 倍長 MAC 鍵 (DATAM)。 MACVER DES MAC 検証鍵および HMAC MAC 検証鍵。 NULL 鍵素材のないレコード。 OPINENC DES 出力 PIN 暗号化鍵。 PINGEN DES PIN 生成鍵。 PINCALC AES PIN 計算鍵。 PINPROT AES PIN 保護鍵。 PINPRW AES PIN 参照値鍵。
4	8		PINVER DES PIN 検証鍵。

メタデータ・フラグを検索基準として使用するには、使用されるフラグおよび値を指定します。

表 7. メタデータ・フラグを使用した検索基準
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	5	検索基準はメタデータ・フラグです。
2	2	6	項目の長さ。
4	1	1	フラグ・タイプ: 値日付 X'01' アーカイブ・フラグを禁止します。
5	1		ラベルの CKDS 鍵タイプ (バイト 65-72): 値 (10 進数) フラグの状態 1 有効。 0 無効。

label_count

方向	タイプ
出力	整数

検索基準に一致する検出されたラベルまたはハンドルの数。これは規則配列内で LABEL キーワードが指定されたときのリスト内の output_list パラメーター内の項目数です。これは規則配列内で COUNT キーワードが指定されたときの KDS 内で検出される一致の総数です。

output_list_length

方向	タイプ
入出力	整数

output_list_length パラメーターは、output_list パラメーターの長さ (バイト) です。入力では、この値は出力用のバッファーのサイズです。出力では、この値は output_list パラメーターで戻されるデータの実際の長さです。

このパラメーターは、規則配列内で COUNT キーワードが指定される場合は無視されます。

output_list

方向	タイプ
出力	文字

検索基準を満たすラベルまたはハンドルのリストのための出力域。ラベルは、各項目が以下に示す固定長である配列に戻されます。

CKDS - 72 バイト
PKDS - 64 バイト
TKDS - 44 バイト

戻されるラベルの数は、output_list_length パラメーターと、KDS によるラベルの長さによって決定されます。label_count パラメーターにはこのリスト内のラベルの数が含まれています。

すべてのラベルを収めるのに十分なスペースがない場合は、戻りコードが 4 で、理由コードは 3033 です。後続の呼び出しのリストを継続するには continuation_area が使用されます。

このパラメーターは、規則配列内で LABELS キーワードが指定された場合にのみ戻されます。

注: CKDS ラベルは 64 バイトのラベルおよび 8 バイトの鍵タイプから構成されます。鍵タイプは鍵の分離に使用されます。

reserved1_length

方向	タイプ
入力	整数

このパラメーターは予約済みです。値はゼロでなければなりません。

reserved1

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

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

reserved2_length

方向	タイプ
入力	整数

このパラメーターは予約済みです。値はゼロでなければなりません。

reserved2

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

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

continuation_area

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

これは、呼び出し側アプリケーションが指定する必要のある 100 バイトの作業域です。continuation_area は、検索基準に一致するすべてのラベルの完全なリストを取得するために、サービスを複数回呼び出すことを可能にする作業域です。ご使用のアプリケーションで、このストリングに含まれるデータを変更してはなりません。

最初の要求の場合、この領域を 2 進ゼロに初期化します。戻りコードはリストが完全であるかどうかを示します。

このパラメーターは、規則配列内で COUNT キーワードが指定される場合は無視されます。

使用上の注意

呼び出し側がこの呼び出し可能サービスを使用するための権限があることを検証するために SAF が呼び出されます。CSFKEYS または CRYPTOZ プロファイルの検査は行われません。

CKDS 内の ICSF システム・キーは、このサービスによってリストされません。

CKDS および PKDS のためのラベル・フィルターの指定

ラベルは最大 64 文字まで含めることができます。先頭文字は、英字または国別文字 (#、$、@) でなければなりません。残りの文字には、英数字、国別文字 (#、$、@)、またはピリオド (.) を使用できます。

label_filter パラメーターは、以下を含むことができる文字ストリングです。

ラベルについて有効な文字を含む文字ストリング。
ワイルドカード ( * (アスタリスク)):
- ワイルドカードは 0 個以上の文字がフィルター処理で無視されることを意味します。
- 無視する文字の数は *(nn) のように指定できます。ここで nn はフィルター処理で無視される文字数 (1 - 63) です。
- フィルターに 0 個から 4 個のワイルドカードを指定することができます。ストリングにワイルドカードがない場合は、鍵データ・セット内のラベルの存在を確認します。
フィルター内のすべての場所でブランクは許可されません。

例

*: すべてのラベル。
*ABC: ABC で終わるすべてのラベル。
*DEF*: ラベル内のどこかに DEF が入っているすべてのラベル。
GHI*: GHI で始まるすべてのラベル。
JKL*MNO: JKL で始まり MNO で終わるすべてのラベル。
*(20)PQR*: 文字 21 に PQR が入っているすべてのラベル。
STU*(6)VWX*: STU で始まり文字 10 に VWX が入っているすべてのラベル。
*(15)YZ1*234: 文字 16 に YZ1 が入っていて 234 で終わるすべてのラベル。
$5*6*7: $5 で始まり、ラベルのどこかに 6 が入っていて、7 で終わるすべてのラベル。

検索基準の例:

日付:
- 比較する値として 2 進ゼロを使用することにより、日付フィールドが設定されていないレコードを検索によって検出できます。検索日付がゼロである場合は以下のようになります。
  レコード作成日
  
  ゼロにできません。
  
  レコード更新日
  
  レコードは更新されません。
  
  鍵素材有効期間開始日
  
  日付は設定されません。
  
  鍵素材有効期間終了日
  
  日付は設定されません。
  
  最後に使用した参照日
  
  レコードは暗号操作で使用されていません。
  
  レコード・アーカイブ日
  
  レコードがアーカイブされた場合、日付をゼロにすることはできません。レコードがアーカイブされていない場合、日付はゼロです。
  
  レコード再呼び出し日
  
  レコードが再呼び出しされた場合、日付をゼロにすることはできません。レコードが再呼び出しされていない場合、日付はゼロです。

必須ハードウェア

この呼び出し可能サービスで必要な暗号化ハードウェアはありません。