TPKEYOPEN(3cbl)

名前

TPKEYOPEN() - デジタル署名の生成、メッセージの暗号化または暗号解読のためのキー・ハンドルのオープン

形式

01 TPKEYDEF-REC. 
   COPY TPKEYDEF.

01 TPSTATUS-REC. 
   COPY TPSTATUS.

CALL "TPKEYOPEN" USING TPKEYDEF-REC TPSTATUS-REC.

機能説明

TPKEYOPEN() によって、呼び出し元でキー・ハンドルを利用できるようになります。 キー・ハンドルは、特定のプリンシパルのキーおよびそれに関連付けられた情報を表します。

キーは、以下に示す目的のうち、1 つまたは複数の目的に使用できます。

TPKEYOPEN() によって返されるキー・ハンドルは、TPKEYDEF-REC 内の KEY-HANDLE に格納されます。

呼び出し側プロセスは TPKEYDEF-REC 内のPRINCIPAL-NAME を設定する必要があります。PRINCIPAL-NAME は、キーの所有者のアイデンティティを指定します。 この名前の末尾には SPACES または LOW-VALUES を埋め込むことができます。 PRINCIPAL-NAME がすべて SPACES か LOW-VALUES の場合、デフォルトのアイデンティティが使用されます。 デフォルトのアイデンティティは、現在のログイン・セッション、現在のオペレーティング・システム・アカウント、またはローカル・ハードウェア・デバイスなどの属性に基づいて決定されます。

呼び出し側プロセスは、TPKEYDEF-REC 内の LOCATION を設定しなければならないことがあります。LOCATION はキー所有者のアイデンティティの位置を指定します。 プロバイダがこのフィールドを要求していない場合は、このフィールドに SPACES か LOW-VALUES を入力できます。

PRINCIPAL-NAME のアイデンティティを認証するために、パスワードまたはパス・フレーズなどの証明材料が要求されることがあります。 必要な場合は、証明材料を TPKEYDEF-REC 内の IDENTITY-PROOF に格納します。 必要ない場合、このフィールドには SPACES か LOW-VALUES を入力できます。

証明材料の長さ (バイト単位) は、TPKEYDEF-REC 内の PROOF-LEN で指定されます。 PROOF-LEN が 0 の場合、IDENTITY-PROOF は末尾に SPACES か LOW-VALUES を埋め込まれた文字列であるとみなされます。この場合、末尾の SPACES や LOW-VALUES は証明材料の一部とはみなされません。

ローカル・マシンのコンフィギュレーションおよび動作環境に基づいて、暗号サービス・プロバイダを選択しなければならないことがあります。 暗号サービス・プロバイダを選択する場合は、必要なプロバイダ名を TPKEYDEF-REC 内の CRYPTO-PROVIDER に設定します。 暗号サービス・プロバイダを選択しない場合、このフィールドに SPACES か LOW-VALUES を入力すると、デフォルトのプロバイダが選択されます。

キーの動作モードに必要なキー・アクセスのタイプは、TPKEYDEF-REC に次の設定を 1 つまたは複数指定することにより決定されます。

これらの設定を組み合わせて、指定することができます。 キーが暗号化にのみ使用される場合 (TPKEY-ENCRYPT および TPKEY-AUTOENCRYPT)、IDENTITY-PROOF は不要です。

戻り値

TPKEYOPEN() は正常終了時には、TPSTATUS-REC 内の TP-STATUS に [TPOK] を設定します。 また、このキーを表す値が TPKEYDEF-REC 内の KEY-HANDLE に設定されます。この値は、TPKEYGETINFO() などほかの関数で使用されます。

エラー

TPKEYOPEN() は異常終了時には、TPSTATUS-REC 内の TP-STATUS に次のいずれかの値を設定します。

関連項目