対称鍵暗号化 (CSNBSYE または CSNBSYE1 および CSNESYE または CSNESYE1)

対称鍵暗号化呼び出し可能サービスは、サポートされるいずれかのモードを使用してデータを暗号化するために使用します。ICSF は、データを暗号化するための複数の処理規則をサポートしています。対称鍵暗号化呼び出し可能サービスがブロック・チェーンに対して使用すべき処理規則のタイプを選択します。詳しくは、操作のモードを参照してください。

処理規則
目的
ANSI X9.23
暗号化ブロック・チェーン用。非暗号化テキストは任意の長さにすることができます。暗号化テキストは、非暗号化テキストより 1 バイトから 8 バイト長くなります。この処理規則は、生成された暗号化テキストがブロック・サイズの正確な倍数となるように、暗号化時に必ず非暗号化テキストに埋め込みを行います。これは、非暗号化テキストが既にブロック・サイズの倍数であった場合も同様です。
CBC
暗号化ブロック・チェーン用。非暗号化テキストは、指定されたアルゴリズムのブロック・サイズ (DES の場合は 8 バイト、AES の場合は 16 バイト) の正確な倍数でなければなりません。暗号化テキストは非暗号化テキストと同じ長さになります。
CBC-CS
暗号化ブロック・チェーン用。非暗号化テキストは、指定されたアルゴリズムのブロック・サイズ (DES の場合は 8 バイト、AES の場合は 16 バイト) 以上でなければなりません。非暗号化テキストは暗号化テキストと同じ長さになります。
CFB
ブロック・サイズと等しいセグメント・サイズで暗号化フィードバックによる暗号化を実行します。非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。
CFB-LCFB
呼び出し側が設定したセグメント・サイズで暗号化フィードバックによる暗号化を実行します。非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。
CTR
カウンター・モード暗号化を実行します。暗号化テキストは任意の長さにすることができます。非暗号化テキストは暗号化テキストと同じ長さになります。
CUSP
暗号化ブロック・チェーン用。非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。
ECB
電子コード・ブック暗号化を実行します。非暗号化テキストは、指定されたアルゴリズムのブロック・サイズ (DES の場合は 8 バイト、AES の場合は 16 バイト) の正確な倍数でなければなりません。暗号化テキストは非暗号化テキストと同じ長さになります。
GCM
Galois/Counter Mode 暗号化を実行します。これにより、非暗号化テキストに対しては機密性と認証の両方が、追加認証データ (AAD) に対しては認証が提供されます。 非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。さらに、データが返される前に、認証タグの検証が行われます。
IPS
暗号化ブロック・チェーン用。非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。
OFB
出力フィードバック・モード暗号化を実行します。非暗号化テキストは任意の長さにすることができます。暗号化テキストは非暗号化テキストと同じ長さになります。
PKCS-PAD
暗号化ブロック・チェーン用。非暗号化テキストは任意の長さにすることができます。暗号化テキストは、非暗号化テキストより 1 バイトから 8 バイト長くなります。この処理規則は、生成された暗号化テキストがブロック・サイズの正確な倍数となるように、必ず暗号化テキストに埋め込みを行います。これは、非暗号化テキストが既にブロック・サイズの倍数であった場合も同様です。

Advanced Encryption Standard (AES) および Data Encryption Standard (DES) がサポートされます。AES 暗号化は、128 ビット、192 ビット、または 256 ビットの鍵を使用します。DES 暗号化は、56 ビット、112 ビット、または 168 ビットの鍵を使用します。制限事項については、処理規則の説明を参照してください。アルゴリズムごとに、使用できない特定の処理規則があります。詳しくは、rule_array パラメーターの説明を参照してください。

ECB 以外のすべてのモードでは、処理を行う際に初期チェーニング・ベクトル (ICV) を使用します。

チェーニングを許容するすべてのモードでは、出力チェーニング・ベクトル (OCV) と呼ばれる結果のチェーン値が生成されます。アプリケーションは、次の暗号化呼び出しで OCV を ICV として渡すことができます。これにより、レコード・チェーンが生成されます。

Single-DES 暗号化モードと Triple-DES 暗号化モードのどちらを選択するかは、key_identifier パラメーターに指定されている鍵の長さによって決まります。 単一長の鍵が指定されている場合、Single-DES 暗号化が実行されます。 倍長の鍵または 3 倍長の鍵が指定されている場合は、Triple-DES 暗号化が実行されます。

鍵は、非暗号化鍵値、内部非暗号化鍵トークン、または CKDS 内の非暗号化鍵または暗号化鍵のラベル名として指定できます。

親トピック: データの保護

CSNBSYE および CSNBSYE1 からの選択

CSNBSYE と CSNBSYE1 は同じ機能を提供します。使用するサービスを選択するときは、以下を考慮してください。
  • CSNBSYE では、非暗号化テキストと暗号化テキストを呼び出し側の 1 次アドレス・スペースに置く必要があります。 また、CSNBSYE を使用するプログラムは IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface に準拠しています。

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

  • CSNBSYE1 では、非暗号化テキストと暗号化テキストを呼び出し側の 1 次アドレス・スペース、またはデータ・スペースのいずれかに置くことができます。これにより、1 回の呼び出しでより多くのデータを暗号化できるようになります。 ただし、CSNBSYE1 を使用するプログラムは IBM Common Cryptographic Architecture: Cryptographic Application Programming Interface に準拠していないため、このプログラミング・インターフェースに準拠する他の暗号化製品で当該プログラムを実行する前に、プログラムの変更が必要になる場合があります。

    CSNBSYE1 では、clear_text_id および cipher_text_id が、非暗号化テキストおよび暗号化テキストを含む、データ・スペースのアクセス・リスト項目トークン (ALET) のパラメーターです。

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

形式

CALL CSNBSYE(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             key_parms_length,
             key_parms,
             block_size,
             initialization_vector_length,
             initialization_vector,
             chain_data_length,
             chain_data,
             clear_text_length,
             clear_text,
             cipher_text_length,
             cipher_text,
             optional_data_length,
             optional_data)
CALL CSNBSYE1(
             return_code,
             reason_code,
             exit_data_length,
             exit_data,
             rule_array_count,
             rule_array,
             key_identifier_length,
             key_identifier,
             key_parms_length,
             key_parms,
             block_size,
             initialization_vector_length,
             initialization_vector,
             chain_data_length,
             chain_data,
             clear_text_length,
             clear_text,
             cipher_text_length,
             cipher_text,
             optional_data_length,
             optional_data,
             clear_text_id,
             cipher_text_id)

パラメーター

return_code
方向 タイプ
出力 整数

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

reason_code
方向 タイプ
出力 整数

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

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

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

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

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

rule_array_count
方向 タイプ
入力 整数

rule_array パラメーターで指定するキーワードの数。 値には 1、2、3、または 4 を指定できます。

rule_array
方向 タイプ
入力 整数

処理制御情報を提供する 8 バイトのキーワードの配列。キーワードは、隣接ストレージ内にあり、左寄せされ、右側にブランクが埋め込まれている必要があります。

表 1. 対称鍵暗号化の規則配列キーワード
キーワード 意味
アルゴリズム (必須)
AES これは、Advanced Encryption Standard (AES) アルゴリズムが使用されることを指定します。ブロック・サイズは 16 バイトです。鍵の長さは、16 バイト、24 バイト、または 32 バイトです。chain_data フィールドの長さは、少なくとも 32 バイトでなければなりません。OCV は、chain_data 内の最初の 16 バイトです。AES は、CUSP、IPS、および X9.23 の処理規則をいずれもサポートしていません。
DES Data Encryption Standard (DES) アルゴリズムを使用することを指定します。DES と TDES のどちらのアルゴリズムを使用するかは、指定された鍵の長さから決定されます。鍵の長さは、8 バイト、16 バイト、または 24 バイトにすることができます。ブロック・サイズは 8 バイトです。chain_data フィールドの長さは、少なくとも 16 バイトでなければなりません。OCV は、chain_data 内の最初の 8 バイトです。DES は、CTR 処理規則と GCM 処理規則をいずれもサポートしていません。
処理規則 (オプション)

規則 CBC-CS、CUSP、IPS、PKCS-PAD、および X9.23 は、要求が 1 つの場合か、またはチェーニングされた一連の要求の最後の要求にのみ指定する必要があります。
CBC CBC モード (暗号化ブロック・チェーン)。テキストの長さは、指定されたアルゴリズムのブロック・サイズの倍数でなければなりません。CBC はデフォルト値です。
CBC-CS 暗号化テキスト・スチーリングを使用した CBC モード (暗号化ブロック・チェーン)。 テキストの長さは、指定されたアルゴリズムのブロック・サイズ以上でなければなりません。
CFB IBM の Encryption Facility 製品と互換性のある CFB モード (暗号化フィードバック)。入力テキストは任意の長さにすることができます。
CFB-LCFB CFB モード (暗号化フィードバック)。この規則により、s (セグメント・サイズ) の値をブロック・サイズ以外の値に設定することができます (CFB 処理規則により、s はブロック・サイズに設定されます)。key_parms_length パラメーターおよび key_parms パラメーターが、s の値を設定するために使用されます。入力テキストは任意の長さにすることができます。
CTR CTR モード (カウンター・モード)。入力テキストは任意の長さにすることができます。
CUSP IBM の CUSP 製品および PCF 製品と互換性のある CBC モード (暗号化ブロック・チェーン)。入力テキストは任意の長さにすることができます。
ECB ECB モード (電子コードブック)。テキストの長さは、指定されたアルゴリズムのブロック・サイズの倍数でなければなりません。
GCM GCM モード (Galois/Counter Mode)。key_parms_length パラメーターおよび key_parms パラメーターが、入力でタグ (値 t) の長さを示し、出力でタグを格納するために使用されます。追加認証データ (AAD) が optional_data_length パラメーターおよび optional_data パラメーターに含まれています。 入力テキストは任意の長さにすることができます。
GCM-LG 処理は GCM 規則と類似しています。clear_text_length または optional_data_length が 256 MiB (2^28 ビット) 以上であり、かつ APAR OA46558 適用前のリリース HCR77A1 以下のレガシー認証タグが生成される場合にのみ使用します。
IPS IBM の IPS 製品と互換性のある CBC モード (暗号化ブロック・チェーン)。入力テキストは任意の長さにすることができます。
OFB OFB モード (出力フィードバック)。入力テキストは任意の長さにすることができます。
PKCS-PAD CBC モード (暗号化ブロック・チェーン) は、必ずしもブロック長 (DES の場合は 8 バイト、AES の場合は 16 バイト) の正確な倍数である必要はありません。PKCS-PAD は、生成された暗号化テキストがブロック長の正確な倍数となり非暗号化テキストより長くなるように、必ず非暗号化テキストに埋め込みを行います。
X9.23 ANSI X9.23 に従って追加された 1 バイトから 8 バイトの埋め込み用の CBC モード (暗号化ブロック・チェーン)。入力テキストは任意の長さにすることができます。
鍵規則 (オプション)
KEY-CLR これは、鍵パラメーターに非暗号化鍵値が含まれることを指定します。KEY-CLR はデフォルトです。
KEYIDENT これは、key_identifier フィールドが、内部非暗号化トークン、または CKDS 内の非暗号化鍵または暗号化鍵のラベル名になることを指定します。標準の CKDS ラベル名構文を使用する必要があります。
ICV 選択 (オプション)
INITIAL これは、initialization_vector パラメーターから初期設定ベクトルを取得することを指定します。INITIAL はデフォルト値です。INITIAL は、処理規則 GCM では無効です。
CONTINUE これは、chain_data パラメーターが指している作業域に含まれている出力チェーニング・ベクトルから初期設定ベクトルを取得することを指定します。CONTINUE は、処理規則 ECB、GCM、および X9.23 では無効です。
FINAL これは、chain_data パラメーターが指している作業域に含まれている出力チェーニング・ベクトルから初期設定ベクトルを取得することを指定します。FINAL の使用は、この呼び出しにデータの最後の部分が含まれることを示します。FINAL は、処理規則 CBC-CS、CFB、CFB-LCBF、CTR、および OFB の場合に有効です。
ONLY これは、initialization_vector パラメーターから初期設定ベクトルを取得すること、および処理するデータ全体がこの単一の呼び出しに含まれることを指定します。 ONLY は、処理規則 CBC-CS、CFB、CFB-LCFB、CTR、GCM、および OFB の場合に有効です。
key_identifier_length
方向 タイプ
入力 整数

key_identifier パラメーターの長さ。非暗号化鍵の場合、この長さはバイト数であり、鍵の値のみを含みます。

KEYIDENT キーワードの場合、このパラメーター値は 64 でなければなりません。

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

KEY-CLR キーワードでは、これは暗号鍵を指定します。パラメーターは左寄せする必要があります。

KEYIDENT キーワードでは、これは内部非暗号化トークン、または CKDS 内の非暗号化鍵または暗号化鍵のラベル名を指定します。標準の CKDS ラベル名構文を使用する必要があります。鍵アルゴリズムには DES または AES を使用できます。鍵タイプは DATA でなければなりません。暗号化鍵のサポートは、IBM System z10 以降のサーバーで利用できます。

key_parms_length
方向 タイプ
入力 整数
key_parms パラメーターの長さ。
  • CFB-LCFB および CTR 処理規則の場合、この長さは 1 にする必要があります。
  • GCM 処理規則の場合、これは、生成される認証タグの長さ (バイト) です。有効な長さは 4、8、12、13、14、15、および 16 です。4 または 8 の長さを使用することは極力避けてください。
  • 他のすべての処理規則では、このフィールドは無視されます。
テキストを復号する際、これと同じ長さを指定する必要があります。
key_parms
方向 タイプ
入出力 ストリング
このパラメーターには、暗号化アルゴリズムと処理モードに固有の鍵関連パラメーターが含まれています。
  • CFB-LCFB 処理規則では、この 1 バイトのフィールドはセグメント・サイズ (バイト) を指定します。 有効な値は 1 からブロック・サイズまでで、両端の値を含みます。 ブロック・サイズは DES では 8、AES では 16 です。
  • CTR 処理規則では、この 1 バイトのフィールドは、増分されるカウンターの下位バイトの数を指定します。残りの上位バイトは nonce です。有効な値は 1 からブロック・サイズまでで、両端の値を含みます。 AES のブロック・サイズは 16 です。
  • GCM 処理規則の場合、これには、提供された非暗号化テキスト (plain_text パラメーター) および追加認証データ (optional_data パラメーター) の生成された認証タグが含まれます。
  • 他のすべての処理規則では、このフィールドは無視されます。
key_parms が使用されるモードでは、対称鍵復号呼び出し可能サービスを使用してテキストを復号するときに、同じ key_parms を指定する必要があります。
block_size
方向 タイプ
入力 整数

このパラメーターには、テキスト・ブロックの処理サイズ (バイト) が含まれています。この値はアルゴリズム固有の値になります。

initialization_vector_length
方向 タイプ
入力 整数

initialization_vector パラメーターの長さ。このパラメーターは ECB 処理規則では無視されます。GCM 処理規則の場合、NIST では長さ 12 を推奨していますが、ゼロ以外の任意の長さも指定できます。他のすべての処理規則では、この長さは、指定されたアルゴリズムのブロック長と等しくなければなりません。

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

初期チェーン値。データを復号するには、同じ ICV を使用する必要があります。このパラメーターは ECB 処理規則では無視されます。

chain_data_length
方向 タイプ
入出力 整数

chain_data パラメーターの長さ。出力では、チェーニング・ベクトルの実際の長さがパラメーターに保管されます。このパラメーターは、ICV 選択キーワードが ONLY の場合は無視されます。

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

このフィールドは、チェーニング・ベクトルのシステム作業域として使用されます。ご使用のアプリケーション・プログラムで、このストリングに含まれるデータを変更してはなりません。 チェーニング・ベクトルには、呼び出し側の出力チェーニング・ベクトルが保持されます。

ICV 選択キーワードが INITIAL の場合、方向は出力です。このパラメーターは、ICV 選択キーワードが ONLY の場合は無視されます。

chain_data のマッピングは、指定されたアルゴリズムによって異なります。AES の場合、chain_data フィールドの長さは、少なくとも 32 バイトでなければなりません。OCV は、chain_data の最初の 16 バイトにあります。DES の場合、chain_data フィールドの長さは、少なくとも 16 バイトでなければなりません。

clear_text_length
方向 タイプ
入力 整数

非暗号化テキストの長さ。GMAC 操作の実行時に GCM 処理規則を使用する場合を除き、clear_text_length パラメーターのゼロ値は無効です。長さは、CBC、ECB、および PKCS-PAD 処理規則ではアルゴリズムのブロック・サイズの倍数でなければなりませんが、他の処理規則では任意の長さにすることができます。 部分ブロック (CFB-LCFB の場合はセグメント) をサポートする処理規則の場合は、最終ブロック (セグメント) を唯一の部分ブロック (セグメント) とすることが推奨されます。 部分ブロックを中間に配置することは、標準の文書で規定されているサポート対象操作ではなく、他の暗号化システムに移植できない場合があります。

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

暗号化するテキスト。

cipher_text_length
方向 タイプ
入出力 整数

入力では、このパラメーターは、cipher_text パラメーターによって示されたストレージのサイズを指定します。 出力では、このパラメーターには、cipher_text パラメーターでアドレス指定されたバッファーに保管されているテキストの実際の長さが入っています。

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

サービスによって返される暗号化テキスト。

optional_data_length
方向 タイプ
入力 整数

optional_data パラメーターの長さ。GCM 処理規則では、このパラメーターには追加認証データ (AAD) の長さが含まれています。このパラメーターは、ゼロを含め、任意の長さにすることができます。他のすべての処理規則では、このフィールドは無視されます。

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

指定されたアルゴリズムで必要なオプション・データ。指定されたアルゴリズムまたは処理モードで必要なオプション・データ。GCM 処理規則では、このパラメーターには追加認証データ (AAD) が含まれています。他のすべての処理規則では、このフィールドは無視されます。

対称鍵復号を使用してテキストを復号する際に、同じ optional_data を指定する必要があります。

clear_text_id
方向 タイプ
入力 整数

CSNBSYE1 の場合のみ、暗号化する非暗号化テキストの ALET。

cipher_text_id
方向 タイプ
入力 整数

CSNBSYE1 の場合のみ、アプリケーションが提供した暗号化テキストの ALET。

使用上の注意

  • 呼び出し側が CKDS に保管されている指定された鍵ラベルの使用を許可されているかを検査するために、SAF が呼び出される場合があります。
  • CKDS 内にある DES または AES で暗号化された DATA 鍵を使用するには、指定された鍵ラベルに関連付けられた CSFKEYS クラス一般リソース・プロファイルの ICSF セグメントに SYMCPACFWRAP(YES) が含まれている必要があります。詳しくは、「z/OS Cryptographic Services ICSF Administrator's Guide」を参照してください。
  • このサービスでは、プリプロセッシング出口もポストプロセッシング出口も使用可能になっていません。
  • マスター鍵は、このサービスを暗号化鍵のラベルと一緒に使用する場合のみロードする必要があります。
  • AES アルゴリズムは、ハードウェアが使用可能な場合、そのハードウェアを使用します。そうではない場合、非暗号化鍵の操作はソフトウェアで実行されます。
  • AES には、Triple-DES と同じ可用性の制限があります。
  • 実行により clear_text フィールドの破壊的なオーバーレイが発生する場合、このサービスは失敗します。

アクセス制御点

key_identifier パラメーターに暗号化鍵のラベルが指定されている場合、以下にリストされた該当するアクセス制御点が使用可能になっていなければなりません。

表 2. 対称鍵暗号化に必要なアクセス制御点
鍵アルゴリズム アクセス制御点
AES Symmetric Key Encipher/Decipher - Encrypted AES keys
DES Symmetric Key Encipher/Decipher - Encrypted DES keys

必須ハードウェア

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

表 3. 対称鍵暗号化の必須ハードウェア
サーバー 必須暗号化ハードウェア 制約事項

IBM eServer zSeries 990
IBM eServer zSeries 890

 CP Assist for Cryptographic Functions

GCM 処理規則はサポートされていません。

CFB-LCFB 処理規則は、key_parms にブロック・サイズと等しいセグメント・サイズが指定されている場合にのみサポートされます。

IBM System z9 EC
IBM System z9 BC

 CP Assist for Cryptographic Functions

GCM 処理規則はサポートされていません。

CFB-LCFB 処理規則は、key_parms にブロック・サイズと等しいセグメント・サイズが指定されている場合にのみサポートされます。

IBM System z10 EC
IBM System z10 BC

 CP Assist for Cryptographic Functions

Crypto Express3 コプロセッサー

GCM 処理規則はサポートされていません。

CFB-LCFB 処理規則は、key_parms にブロック・サイズと等しいセグメント・サイズが指定されている場合にのみサポートされます。

暗号化鍵には、2009 年 11 月以降のライセンス内部コード (LIC) を持つ CEX3C が必要です。

IBM zEnterprise 196
IBM zEnterprise 114

 CP Assist for Cryptographic Functions

Crypto Express3 コプロセッサー

暗号化鍵には、2009 年 11 月以降のライセンス内部コード (LIC) を持つ CEX3C が必要です。

IBM zEnterprise EC12
IBM zEnterprise BC12

 CP Assist for Cryptographic Functions

Crypto Express3 コプロセッサー

Crypto Express4 CCA コプロセッサー

IBM z13

 CP Assist for Cryptographic Functions

Crypto Express5 CCA コプロセッサー

  

関連情報

非暗号化テキスト・フィールドと暗号化テキスト・フィールドを破壊的にオーバーラップすることはできません。以下に例を示します。
pppppp
     cccccc  is not supported.

cccccc
     pppppp  is supported.  

ppppppcccccc is supported.

p represents the plaintext and c represents the ciphertext.

OCV の生成に使用される方法は、CBC 処理規則と X9.23 処理規則では同じです。しかし、この方法は、CUSP 処理規則および IPS 処理規則で使用される方法とは異なります。

暗号処理規則に、暗号処理規則についての説明があります。