鍵データ・セット・メタデータ読み取り (CSFKDMR および CSFKDMR6)

CKDS、PKDS、または TKDS レコードのメタデータを取得するには、鍵データ・セット読み取り呼び出し可能サービスを使用します。要求されるメタデータは、1 つ以上のデータのタイプとなる場合があります。

PKCS #11 トークン・オブジェクトのみメタデータがあることに注意してください。PKCS #11 トークンは TKDS 内にレコードを持ちますが、メタデータがありません。

任意の鍵データ・セットであらゆるフォーマットで使用できるメタデータは、以下のとおりです。

レコード作成日: レコードが KDS 内で作成された日時。
レコード更新日: レコードの鍵素材またはメタデータが最後に変更された日時。

任意の鍵データ・セットで KDSR フォーマットで使用できる追加のメタデータは、以下のとおりです。

鍵素材有効期間開始日: 鍵素材がアクティブになる日付。
鍵素材有効期間終了日: 鍵素材がアクティブである最後の日付。
最後の参照日: 鍵素材が最後に参照された日付。この日付は KDSREFDAYS オプションの設定によって異なります。
レコード・アーカイブ日: レコード・アーカイブ済みフラグが KDS メタデータ書き込みサービスによって有効にされた日付。
レコード再呼び出し日: レコード・アーカイブ済みフラグが KDS メタデータ書き込みサービスによって無効にされた日付。
ユーザー・データ: CKDS (CKDUDATA)、PKDS (PKDUDATA)、または TKDS (TKDUDATA) という古いフォーマットでユーザー・データ・フィールドに格納されたデータ。
レコード・アーカイブ済みフラグ: 有効にすると、レコードがアプリケーションによって参照されるときに鍵素材を使用できません。
レコード・アーカイブ禁止フラグ: 有効である場合、レコードはアーカイブできません。
可変長メタデータ・ブロック: IBM タグおよびインストール・システム・タグの両方を指定できます。

注: 鍵データ・セットを KDSR フォーマットに変換するには、調整 KDS 管理呼び出し可能サービス (CSFCRC および CSFCRC6)を参照してください。

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

形式

CALL CSFKDMR (
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             record_label,
             metadata_list_length,
             metadata_list,
             output_list_length,
             output_list,
             reserved1_length,
             reserved1,
             reserved2_length,
             reserved2)

パラメーター

return_code

方向	タイプ
出力	整数

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

reason_code

方向	タイプ
出力	整数

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

exit_data_length

方向	タイプ
入出力	整数

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

exit_data

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

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

rule_array_count

方向	タイプ
入力	整数

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

rule_array

方向	タイプ
入力	文字

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

表 1. KDS メタデータ読み取り制御情報のキーワード
キーワード	意味
鍵データ・セット (必須)
CKDS	ラベルがアクティブな CKDS にあることを指定します。
PKDS	ラベルがアクティブな PKDS にあることを指定します。
TKDS	ラベルがアクティブな TKDS にあることを指定します。

record_label

方向	タイプ
入力	文字

処理されるレコードのラベルまたはハンドル。ラベルの長さはアクセスされる KDS についての最大のラベルの長さです。

CKDS: 72 バイト。
最後の 8 バイトがブランクの場合、サービスは最初に 64 バイトのラベルが固有であることを確認します。ラベルが固有でない場合、要求は失敗します。
PKDS: 64 バイト。
TKDS: 44 バイト。

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

metadata_list_length

方向	タイプ
入力	整数

metadata_list_length パラメーターは、metadata_list パラメーターの長さ (バイト) です。最大値は 250 です。

metadata_list

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

metadata_list パラメーターは、読み取られるメタデータを識別する項目のリストです。metadata_list は、連続するストレージ内の項目のブロックです。

リスト内の各項目は、読み取られる特定のメタデータを識別します。各項目は、表 2 に示す構造を使用します。

表 2. メタデータ項目
オフセット (10 進数)	バイト数	説明
0	2	この構造の長さ。この値はこのフィールドの長さを含みます。可変メタデータ・ブロック要求の場合、この値は 6 です。他のすべての要求の場合、値は 4 です。
2	2	読み取られるメタデータのタイプ: 値意味 X'0001' 可変メタデータ・ブロック。 X'0002' レコード作成日。 X'0003' レコード更新日。 X'0004' 鍵素材有効期間開始日。 X'0005' 鍵素材有効期間終了日。 X'0006' 最後の参照日 (YYYYMMDD)。 X'0007' 最後の参照日 (Store Clock 拡張命令によって戻される値の先頭 8 バイト)。 X'0008' レコード・アーカイブ日。 X'0009' レコード・アーカイブ・フラグ。 X'000A' レコード・アーカイブ禁止フラグ。 X'000B' レコード再呼び出し日。
4	2	可変メタデータ・ブロック要求の場合のみ: メタデータの 2 バイト・タグ。他のすべての要求の場合、このフィールドは使用されません。

output_list_length

方向	タイプ
入出力	整数

output_list_length パラメーターは、output_list パラメーターの長さ (バイト) です。入力では、output_list 領域のサイズの値。出力では、この値は output_list パラメーターで戻されるデータの実際の長さです。最大値は 1000 です。

output_list

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

要求されたメタデータの出力域。出力は、メタデータ・リストに対応するメタデータのリストです。output_list は、連続するストレージ内の出力構造のブロックです。

表 3. 可変メタデータ・ブロックの出力構造
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2		このブロックの長さ。この値はこのフィールドの長さを含みます。
2	2	1	読み取られるメタデータのタイプ: メタデータ・ブロック。
4	2		タグ: 値意味 X'0001' インストール・システム・ユーザー・データ。 X'0002' 参照のためのサービス。 X'0003' レコード・アーカイブ日。 X'0004' レコード再呼び出し日。 X'8000'-X'FFFF' インストール・システム・メタデータ。
6	2		このブロック内のオフセット 8 にあるメタデータの長さ。長さがゼロの場合、メタデータ・タグがレコード内に見つかりませんでした。
8	変数		可変長メタデータ。

表 4. レコード作成日および更新日の出力構造
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	20	このブロックの長さ。この値はこのフィールドの長さを含みます。
2	2		読み取られるメタデータのタイプ: 値意味 X'0002' レコード作成日。 X'0003' レコード更新日。
4	16		EBCDIC でのレコード日付 (YYYYMMDD HHMMSSTH)。日付がレコードに設定されていない場合は、日付は 2 進ゼロです。

表 5. 鍵素材有効期間、アーカイブ、再呼び出し、および最後の参照日の出力構造
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	12	このブロックの長さ。この値はこのフィールドの長さを含みます。
2	2		読み取られるメタデータのタイプ: 値意味 X'0004' 鍵素材有効期間開始日。 X'0005' 鍵素材有効期間終了日。 X'0006' 最後に使用した参照日 (YYYYMMDD)。 X'0007' 最後に使用した参照日 (STCKE)。 X'0008' レコード・アーカイブ日。 X'000B' レコード再呼び出し日。
4	8		鍵素材有効期間、アーカイブ、再呼び出し、および最後に使用された参照日について、日付は EBCDIC の YYYYMMDD フォーマットです。最後に使用される参照日 (STCKE) の場合、これは Store Clock 拡張命令によって戻される値の先頭 8 バイトです。日付がレコードに設定されていない場合は、日付は 2 進ゼロです。

表 6. フラグの出力構造
オフセット (10 進数)	バイト数	値 (10 進数)	説明
0	2	5	このブロックの長さ。この値はこのフィールドの長さを含みます。
2	2		読み取られるメタデータのタイプ: 値意味 X'0009' レコード・アーカイブ・フラグ。 X'000A' レコード・アーカイブ禁止フラグ。
4	1		フラグの状態: 値 (10 進数) 意味 0 フラグは無効です。 1 フラグは有効です。

reserved1_length

方向	タイプ
入力	整数

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

reserved1

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

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

reserved2_length

方向	タイプ
入力	整数

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

reserved2

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

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

使用上の注意

呼び出し側がこの呼び出し可能サービスを使用するための権限があることを検証するために SAF が呼び出されます。

処理される CKDS または PKDS レコードについての CSFKEYS プロファイルは SAF 検査されません。処理される PKCS #11 トークンについての CRYPTOZ プロファイルは SAF 検査されません。

必須ハードウェア

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