PKCS #11 片方向ハッシュ、署名、または検証 (CSFPOWH および CSFPOWH6)

指定されたテキストでの片方向ハッシュの生成、指定されたテキストの署名、または指定されたテキストでの署名の検証を行うには、「片方向ハッシュ、署名、または検証」呼び出し可能サービスを使用します。 片方向ハッシュについては、このサービスは以下の方法をサポートします。

  • MD2 - ソフトウェアのみ
  • MD5 - ソフトウェアのみ
  • SHA-1
  • RIPEMD-160 - ソフトウェアのみ
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512
署名および検証については、以下の方法がサポートされています。
  • RSA-PKCS 1.5 での MD2
  • RSA-PKCS 1.5 での MD5
  • RSA-PKCS 1.5、RSA-PKCS PSS、DSA、または ECDSA での SHA1
  • RSA-PKCS 1.5、RSA-PKCS PSS、DSA、または ECDSA での SHA-224
  • RSA-PKCS 1.5、RSA-PKCS PSS、DSA、または ECDSA での SHA-256
  • RSA-PKCS 1.5、RSA-PKCS PSS、DSA、または ECDSA での SHA-384
  • RSA-PKCS 1.5、RSA-PKCS PSS、DSA、または ECDSA での SHA-512
  • ハッシュなしの RSA-PKCS PSS

呼び出し可能サービスは、AMODE(24)、AMODE(31)、または AMODE(64) で呼び出すことができます。64 ビットの呼び出し側は CSFPOWH6 を使用する必要があります。

親トピック: PKCS #11 トークンおよびオブジェクトの使用

形式

CALL CSFPOWH(	
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             text_length,
             text,
             text_id,
             chain_data_length,
             chain_data,
             handle,
             hash_length,
             hash)

パラメーター

return_code
方向 タイプ
出力 整数

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

reason_code
方向 タイプ
出力 整数

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

exit_data_length
方向 タイプ
無視される 整数

このフィールドは無視されます。 このパラメーターには 0 を指定することをお勧めします。

exit_data
方向 タイプ
無視される ストリング

このフィールドは無視されます。

rule_array_count
方向 タイプ
入力 整数
rule_array パラメーターで指定するキーワードの数。 この値は 1 または 2 でなければなりません。
rule_array
方向 タイプ
入力 ストリング
制御情報を呼び出し可能サービスに提供するキーワード。 キーワードはそれぞれ、8 バイト・フィールドで左寄せされ、右側にブランクが埋め込まれます。 キーワードはすべて、連続するストレージ内になければなりません。
表 1. 片方向ハッシュの生成のキーワード
キーワード 意味
ハッシュ方式 (必須)
MD2 ハッシュ・アルゴリズムは MD2 アルゴリズムです。生成されるハッシュの長さは 16 バイトです。
MD5 ハッシュ・アルゴリズムは MD5 アルゴリズムです。生成されるハッシュの長さは 16 バイトです。
RPMD-160 ハッシュ・アルゴリズムは RIPEMD-160 です。生成されるハッシュの長さは 20 バイトです。
SHA-1 ハッシュ・アルゴリズムは SHA-1 です。生成されるハッシュの長さは 20 バイトです。
SHA-224 ハッシュ・アルゴリズムは SHA-224 です。生成されるハッシュの長さは 28 バイトです。
SHA-256 ハッシュ・アルゴリズムは SHA-256 です。生成されるハッシュの長さは 32 バイトです。
SHA-384 ハッシュ・アルゴリズムは SHA-384 です。生成されるハッシュの長さは 48 バイトです。
SHA-512 ハッシュ・アルゴリズムは SHA-512 です。生成されるハッシュの長さは 64 バイトです。
SHA1LG ハッシュ・アルゴリズムは SHA-1 アルゴリズムによく似ています。 これは、text_length が 256 メガバイト (HCR7770 上の IBM eServer zSeries 990 または IBM eServer zSeries 890 以降の ハードウェアでは 512 メガバイト) 以上の場合にのみ使用します。 このハッシュ方式は DSS に使用します (片方向ハッシュ生成にのみ適用されます)。 生成されるハッシュの長さは 20 バイトです。 APAR OA43937 より前のリリース HCR7770 以降のレガシー・ハッシュ値は、以前にアーカイブされたハッシュ値を使用して検証目的で生成されます。
SHA224LG ハッシュ・アルゴリズムは SHA-224 アルゴリズムによく似ています。 これは、text_length が 256 メガバイト (HCR7770 上の IBM eServer zSeries 990 または IBM eServer zSeries 890 以降の ハードウェアでは 512 メガバイト) 以上の場合にのみ使用します。 生成されるハッシュの長さは 28 バイトです。 APAR OA43937 より前のリリース HCR7770 以降のレガシー・ハッシュ値は、以前にアーカイブされたハッシュ値を使用して検証目的で生成されます。
SHA256LG ハッシュ・アルゴリズムは SHA-256 アルゴリズムによく似ています。 これは、text_length が 256 メガバイト (HCR7770 上の IBM eServer zSeries 990 または IBM eServer zSeries 890 以降の ハードウェアでは 512 メガバイト) 以上の場合にのみ使用します。 生成されるハッシュの長さは 32 バイトです。 APAR OA43937 より前のリリース HCR7770 以降のレガシー・ハッシュ値は、以前にアーカイブされたハッシュ値を使用して検証目的で生成されます。
SHA384LG ハッシュ・アルゴリズムは SHA-384 アルゴリズムによく似ています。 これは、text_length が 256 メガバイト (HCR7770 上の IBM eServer zSeries 990 または IBM eServer zSeries 890 以降の ハードウェアでは 512 メガバイト) 以上の場合にのみ使用します。 生成されるハッシュの長さは 48 バイトです。 APAR OA43937 より前のリリース HCR7770 以降のレガシー・ハッシュ値は、以前にアーカイブされたハッシュ値を使用して検証目的で生成されます。
SHA512LG ハッシュ・アルゴリズムは SHA-512 アルゴリズムによく似ています。 これは、text_length が 256 メガバイト (HCR7770 上の IBM eServer zSeries 990 または IBM eServer zSeries 890 以降の ハードウェアでは 512 メガバイト) 以上の場合にのみ使用します。 生成されるハッシュの長さは 64 バイトです。 APAR OA43937 より前のリリース HCR7770 以降のレガシー・ハッシュ値は、以前にアーカイブされたハッシュ値を使用して検証目的で生成されます。
DETERMIN チェーニングされていない RSA 署名の検証にのみ使用されます。ハッシュ・アルゴリズムは入力署名から決定されます。
NULL チェーニングされていない署名の生成および検証にのみ使用されます。ハッシュは実行されません。テキスト・パラメーター内のデータは、chain_data PSS マスクで指定された同じハッシュ・アルゴリズムの出力でなければなりません。SIGN-PSS または VER-PSS との組み合わせでのみ指定できます。
チェーニング・フラグ (オプション)
FIRST これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける最初の呼び出しであることを指定します。 中間結果は hash フィールドおよび chain_data フィールドに保管されます。 ハッシュ方式 DETERMIN とともに指定することはできません。
MIDDLE これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける中間の呼び出しであることを指定します。 中間結果は hash フィールドおよび chain_data フィールドに保管されます。 ハッシュ方式 DETERMIN とともに指定することはできません。
LAST これは、当該呼び出しが、チェーニングされた一連の呼び出しにおける最後の呼び出しであることを指定します。ハッシュ方式 DETERMIN とともに指定することはできません。
ONLY これは、当該呼び出しが唯一の呼び出しでありチェーニングされていないことを指定します。 これがデフォルトです。
要求された操作 (オプション)
HASH 指定されたテキストはハッシュのみ実行されます。これがデフォルトです。ハッシュ方式 DETERMIN と一緒に (明示的にまたはデフォルトで) 指定できません。
SIGN-RSA データはハッシュされた後、RSA-PKCS 1.5 フォーマットを使用して署名されます。RPMD-160 および DETERMIN を除くすべてのハッシュ方式が許容されます。
SIGN-PSS データはオプションでハッシュされた後、RSA-PKCS PSS フォーマットを使用して署名されます。ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、SHA-512、または NULL でなければなりません。NULL でない場合、ハッシュ方式は chain_data のハッシュ方式と一致する必要があります。
SIGN-DSA データはハッシュされた後、DSA を使用して署名されます。 ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、または SHA-512 でなければなりません。
SIGN-EC データはハッシュされた後、ECDSA を使用して署名されます。 ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、または SHA-512 でなければなりません。
VER-RSA データはハッシュされた後、RSA-PKCS 1.5 フォーマットを使用して署名が検証されます。RPMD-160 を除くすべてのハッシュ方式が許容されます。この操作はハッシュ方式 DETERMIN について必要です。
VER-PSS データはオプションでハッシュされ、RSA-PKCS PSS フォーマットを使用して署名が検証されます。 ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、SHA-512、または NULL でなければなりません。NULL でない場合、ハッシュ方式は chain_data のハッシュ方式と一致する必要があります。
VER-DSA データはハッシュされた後、DSA を使用して署名が検証されます。ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、または SHA-512 でなければなりません。
VER-EC データはハッシュされた後、ECDSA を使用して署名が検証されます。ハッシュ方式は、SHA-1、SHA-224、SHA-256、SHA-384、または SHA-512 でなければなりません。
text_length
方向 タイプ
入力 整数
テキスト・パラメーターの長さ (バイト)。

FIRST または MIDDLE キーワードを指定する場合は、テキストの長さはハッシュ方式のブロック・サイズの倍数でなければなりません。MD2 の場合、これは 16 バイトの倍数です。MD5、RPMD-160、SHA-1、SHA-224、および SHA-256 の場合、これは 64 バイトの倍数です。SHA-384 および SHA-512 の場合、これは 128 バイトの倍数です。ONLY および LAST の場合、このサービスでは、指定されたアルゴリズムに従って必要な埋め込みが行われます。 長さは 0 から 2147483647 にすることができます。

NULL が指定された場合、text_length は chain_data PSS マスクで指定された SHA ハッシュ方式の出力の長さに一致する必要があります。

text
方向 タイプ
入力 ストリング
ハッシュされる値
text_id
方向 タイプ
入力 整数
テキストが存在するスペースを識別する ALET。
chain_data_length
方向 タイプ
入出力 整数
chain_data パラメーターのバイト長。 この値は 128 バイトでなければなりません。
chain_data
方向 タイプ
入出力 ストリング
このフィールドは 128 バイトの作業域です。チェーン・データでは、ある呼び出しから別の呼び出しへのデータのチェーニングが許可され、特定の操作についての初期設定値の引き渡しが可能です。ICSF は FIRST 呼び出しでチェーン・データを初期化し、後続の MIDDLE 呼び出しでこれを変更できます。ご使用のアプリケーションで、特定のメッセージに対する一連の FIRST、MIDDLE、および LAST 呼び出しの間に、このフィールドに含まれるデータを変更してはなりません。 チェーン・データのフォーマットは以下の通りです。
表 2. 入力での chain_data パラメーター・フォーマット (SIGN-PSS および VER-PSS については FIRST および ONLY)
オフセット 長さ 呼び出し側によって提供された初期設定値
0 4 ハッシュ方式。
NULL が指定されなかった場合、rule_array に指定されたメソッドと一致する必要があります。

0x00000220 (CKM_SHA_1)
0x00000255  (CKM_SHA224)
0x00000250  (CKM_SHA256)                                                    
0x00000260  (CKM_SHA384)                                                        
0x00000270  (CKM_SHA512)

4 4 PSS マスク生成関数。
ハッシュ方式と同じダイジェスト・メソッドでなければなりません。

0x00000001  (CKG_MGF1_SHA1)、
0x00000005  (CKG_MGF1_SHA224)、
0x00000002  (CKG_MGF1_SHA256)、
0x00000003  (CKG_MGF1_SHA384)、
0x00000004  (CKG_MGF1_SHA512) のみ。
8 4 PSS ソルトの長さ (バイト)。SIGN-PSS の場合、この値は 0 またはハッシュ方式によって生成されたハッシュのサイズでなければならず、RSA PSS メカニズム用の PKCS #1 標準によって指定された最大のソルトの長さより小さいか等しくなければなりません。SIGN-VER の場合、この値は RSA PSS メカニズム用の PKCS #1 標準によって指定された最大のソルトの長さより小さいか等しくなければなりません。
12 116 予約済み - ICSF によって初期化
表 3. 入力での chain_data パラメーター・フォーマット (PSS 以外の操作については FIRST および ONLY)
オフセット 長さ 説明
0 128 予約済み - ICSF によって初期化
表 4. 出力 (すべての呼び出し) および入力 (MIDDLE および LAST) での chain_data パラメーター・フォーマット
オフセット 長さ 説明
0 4 フラグ・ワード
ビット
オンに設定されたときの意味
0
暗号状態オブジェクトが割り振られています
1-31
IBM で使用するために予約済み
4 44 暗号状態オブジェクト・ハンドル
48 80 IBM で使用するために予約済み
handle
方向 タイプ
入力 ストリング
ハッシュ要求の場合、これはこのハッシュ操作が関連付けられるトークンの 44 バイトの名前です。ハンドルの最初の 32 バイトが意味を持ちます。残りの 12 バイトは予約済みです。handle のフォーマットについては ハンドルを参照してください。

署名要求および検証要求の場合、これは使用される鍵オブジェクトへの 44 バイトのハンドルです。FIRST および MIDDLE のチェーニング要求の場合、ハンドルの最初の 32 バイトのみがトークンを識別するために意味を持ちます。

hash_length
方向 タイプ
入出力 整数
提供されるハッシュ・フィールドのバイト単位の長さ。

ハッシュ要求の場合、このフィールドは入力のみです。 SHA-1 および RPMD-160 の場合、これは少なくとも 20 バイトでなければならず、MD2 および MD5 の場合、これは少なくとも 16 バイトでなければなりません。SHA-224 および SHA-256 の場合、これは少なくとも 32 バイトでなければなりません。 SHA-224 ハッシュの長さが SHA-256 より短い場合でも、ハッシュ値の生成時に追加のバイトが作業域として使用されます。SHA-224 値は左寄せされ、4 バイトの 2 進ゼロが埋め込まれます。SHA-384 および SHA-512 の場合、これは少なくとも 64 バイトでなければなりません。SHA-384 ハッシュの長さが SHA-512 より短い場合でも、ハッシュ値の生成時に追加のバイトが作業域として使用されます。 SHA-384 値は左寄せされ、16 バイトの 2 進ゼロが埋め込まれます。

FIRST および MIDDLE の署名要求および検証要求の場合、このフィールドは無視されます。

LAST および ONLY の署名要求の場合、このフィールドは入出力です。署名生成が正常に実行された場合、ICSF は生成された署名の長さでこのフィールドを更新します。提供されたハッシュ・フィールドが小さすぎるために署名生成が正常に実行されなかった場合、ICSF はこのフィールドを必要な長さで更新します。

LAST および ONLY の検証要求の場合、このフィールドは入力のみです。

hash
方向 タイプ
入出力 ストリング
このフィールドにはハッシュまたは署名が左寄せで入ります。 フィールドの残りの処理は、実装環境によって異なります。

ハッシュ要求の場合、このフィールドは生成されたハッシュです。 FIRST キーワードまたは MIDDLE キーワードを指定する場合、このフィールドには中間ハッシュ値が含まれます。 ご使用のアプリケーションで、特定のメッセージに対する一連の FIRST、MIDDLE、および LAST 呼び出しの間に、 このフィールドに含まれるデータを変更してはなりません。

FIRST および MIDDLE の署名要求および検証要求の場合、このフィールドは無視されます。

LAST および ONLY の署名要求の場合、このフィールドは生成された署名です。

LAST および ONLY の検証要求の場合、このフィールドは検証される入力署名です。

許可

このサービスを、共通オブジェクトでの署名または検証のために使用するには、呼び出し側は少なくとも SO (READ) 権限または USER (READ) 権限 (任意のアクセス) を持つ必要があります。

このサービスを、秘密オブジェクトでの署名または検証のために使用するには、呼び出し側は少なくとも USER (READ) 権限 (ユーザー・アクセス) を持つ必要があります。

使用上の注意

チェーニングされた一連の呼び出しを開始するために FIRST 規則が使用される場合、アプリケーションはハッシュ方式または要求された操作規則を呼び出し間で変更できません。規則が変更された場合、サービスの動作は定義されません。

チェーニングされた一連の呼び出しを開始するために FIRST 規則が使用される場合、アプリケーションは割り当て済みの ICSF リソースを解放するために LAST 呼び出しを行う必要があります。 LAST 呼び出しを行わずに処理が中止され、暗号状態オブジェクトが割り当てられたことが chain_data パラメーターによって示される場合、呼び出し側は、状態オブジェクトのハンドルを渡す CSFPTRD (あるいは 64 ビットの呼び出し側の場合は CSFPTRD6) を呼び出すことによってオブジェクトを解放する必要があります。

このサービスを保護する CSFSERV リソース名は CSFOWH で、非 PKCS #11 片方向ハッシュ・サービスを保護するために使用されるものと同じリソース名です。

CSF.CSFSERV.AUTH.CSFOWH.DISABLE リソース・プロファイルが XFACILIT SAF リソース・クラスで定義されている場合は、このサービスの使用時に CSFSERV クラスに対して SAF 許可検査は行われません。 CSF.CSFSERV.AUTH.CSFOWH.DISABLE が定義されていない場合は、SAF 許可検査が行われます。 SAF 検査を無効にすると、ご使用のアプリケーションのパフォーマンスが向上する可能性があります。

ハッシュ方式 DETERMIN の場合、ICSF は RSA によって、指定された公開鍵を使用して入力署名を復号して結果を検査することによって、ハッシュ方式を決定します。この処理が以下のいずれかの理由で成功しない場合、ICSF は「シグニチャーは検査しませんでした」エラー (戻りコード 4、理由コード X'2AF8') を返します。
  1. 公開鍵のサイズが間違っているため、ICSF が暗号化解除を正常に実行できない。
  2. 結果として得られる非暗号化テキスト・ブロックが、RSA-PKCS 1.5 のフォーマットに正しく設定されていない。
  3. 結果として得られる非暗号化テキスト・ブロックに、このサービスによってサポートされないハッシュ・アルゴリズムが使用されたことが示される。