KMFCryptoOperation:スコープ指定、グローバル

オーストラリア API リファレンス

Release

australia

ft:locale

ja-JP

ft:publication_title

オーストラリア API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

KMFCryptoOperation:スコープ指定、グローバル

リリースバージョン: Australia

更新日 2026年03月12日

所要時間：24分

KMFCryptoOperation クラスは、キー管理フレームワーク (KMF) 暗号化モジュールまたはフィールド暗号化暗号化モジュールを使用して暗号化操作を実行するためのメソッドを提供します。

この API を使用するには、KMF 暗号化モジュールまたは CLE 暗号化モジュールを既に作成して設定しておく必要があります。モジュールには 1 つ以上の暗号化仕様が必要であり、関連するキーを作成またはインポートする必要があります。詳細については、「暗号化モジュール」を参照してください。

この API を使用して生成された KMFCryptoOperation オブジェクトは、対称暗号化などの暗号化操作を表します。このオブジェクトを作成するには KMFCryptoOperations() メソッドを使用し、ビルダーメソッドを使用してオブジェクトのプロパティを設定し、 doOperation() メソッドを使用して操作を実行します。

この API は、スコープ対象アプリケーションとグローバルアプリケーションの両方で使用できます。この API を呼び出すときは、常に sn_kmf_ns 名前空間を指定する必要があります。

KMFCryptoOperation:KMFCryptoOperation(文字列 cryptoModuleName, 文字列 operationName)

指定されたモジュールと操作の KMFCryptoOperation オブジェクトを作成します。

この API はビルダーメソッドを利用します。ビルダーメソッドは、データの目的の出力形式の変更など、KMFCryptoOperation オブジェクトのプロパティを更新します。すべてのビルダーメソッドがすべての操作に有効であるわけではありません。各操作で使用できるビルダーメソッドを、以下のパラメーターテーブルに示します。

次のビルダーメソッドは、すべての操作タイプに有効です。

重要:

このドキュメントで使用される Base64 入力値は、URL セーフである必要があります (A から Z、a から z、0 から 9、ダッシュ (-)、アンダースコア (_) 文字のみを含む)。

表 : 1. パラメーター
名前	タイプ	説明
cryptoModuleName	文字列	使用するキー管理フレームワーク (KMF) 暗号化モジュールまたはフィールド暗号化暗号化モジュールの名前。このメソッドを呼び出す前に、モジュールを作成する必要があります。詳細については、「暗号化モジュールの概要」を参照してください。
operationName	文字列	実行する操作の名前。有効な値 (値の大文字と小文字を区別しない)： ASYMMETRIC_DECRYPTION:非対称キーアルゴリズムを使用したデータの復号化。非対称データ復号化暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAdditionalInput() デフォルトの入力形式:フォーマット済み:KMF 仕様に合わせてフォーマットされますデフォルトの出力形式:KMFBase64 - Base64 エンコードデフォルトの出力タイプ:文字列 ASYMMETRIC_ENCRYPTION:非対称キーアルゴリズムを使用したデータの暗号化。非対称データ暗号化の目的を持つ KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAdditionalInput() デフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列。出力は KMFEncryptionPayload オブジェクトにすることもできます。RSAとEC-IESは、両方と互換性があります。KMFEncryptionPayload オブジェクトの詳細については、「 withAdditionalInput()」を参照してください。 ASYMMETRIC_UNWRAPPING:非対称キーアルゴリズムを使用したキーのラップ解除。非対称キーのラップ解除暗号化の目的を持つ KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAlgorithm() デフォルトの入力形式:フォーマット済み:KMF 仕様に合わせてフォーマットされますデフォルトの出力形式:KMFBase64 - Base64 エンコードデフォルトの出力タイプ:文字列 ASYMMETRIC_WRAPPING:非対称キーアルゴリズムを使用したキーラッピング。非対称キーラッピング暗号化の目的を持つ KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAlgorithm()、 withSysId() デフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列 JWT_SIGN:非対称キーアルゴリズムを使用して JSON Web トークン (JWT) 署名を生成します。署名生成暗号化を目的とした KMF 暗号化モジュールが必要です。JWT ヘッダーは、 withAdditionalInput() メソッドを介して渡す必要があります。生成された JWT は、公開鍵マテリアルにアクセスできる外部システムによって検証できます。追加のビルダーメソッド:withAdditionalInput() デフォルトの入力形式:文字列、JSON 形式の JWT ペイロードデフォルトの出力形式:文字列、完全な JWT トークン (header.payload.signature) デフォルトの出力タイプ:文字列 JWT_VERIFY:非対称キーアルゴリズムを使用した JSON Web トークン (JWT) 署名検証。署名検証暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド:なし。デフォルトの入力形式:文字列、完全な JWT トークン (header.payload.signature) デフォルトの出力形式:有効性ステータス、デコードされたヘッダー、およびデコードされたペイロードを含む文字列デフォルトの出力タイプ:文字列。署名の有効性 (true/false) を持つ JSON オブジェクトを返し、検証に成功した場合はデコードされた JWT コンポーネントを返します。ServiceNow インスタンスの内部と外部の両方で生成された JWT を検証できます。 MAC_GENERATION:メッセージ認証コード (MAC) の生成。データの完全性と認証を提供する対称キーアルゴリズムに基づく。対称真正性暗号化の目的を持つ KMF 暗号化モジュールが必要です。追加のビルダーメソッド:なしデフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列 MAC_VERIFICATION:MAC の検証。データの完全性と認証を提供する対称キーアルゴリズムに基づく。対称真正性暗号化の目的を持つ KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAdditionalInput() デフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:KMFNone - デコードなしデフォルトの出力タイプ:ブーリアン SIGNATURE_GENERATION:デジタル署名の生成。データの完全性と認証を提供する非対称キーアルゴリズムに基づく。署名生成暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド:なしデフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列 SIGNATURE_VERIFICATION:デジタル署名の検証。データの完全性と認証を提供する非対称キーアルゴリズムに基づく。署名検証暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAdditionalInput() デフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:KMFNone - デコードなしデフォルトの出力タイプ:ブーリアン SYMMETRIC_ENCRYPTION:対称キーアルゴリズムを使用したデータの暗号化。アルゴリズムが等価性保存でない場合は、フォーマットされた出力のみが許可されます。対称データの暗号化/復号化の暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド:なしデフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列 SYMMETRIC_DECRYPTION:対称キーアルゴリズムを使用したデータの復号化。アルゴリズムが等価性保存でない場合は、KMFBase64 入力が許可されます。対称データの暗号化/復号化の暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド:なしデフォルトの入力形式:フォーマット済み:KMF 仕様に合わせてフォーマットされますデフォルトの出力形式:KMFBase64 - Base64 エンコードデフォルトの出力タイプ:文字列 SYMMETRIC_WRAPPING:対称キーアルゴリズムを使用したキーラッピング。アルゴリズムが等価性保存でない場合は、フォーマットされた出力のみが許可されます。対称キーラッピング/ラップ解除の暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAlgorithm() および withSysId() デフォルトの入力形式:KMFBase64 - Base64 エンコードデフォルトの出力形式:フォーマット済み:KMF 仕様に合わせてフォーマットデフォルトの出力タイプ:文字列 SYMMETRIC_UNWRAPPING:対称キーアルゴリズムを使用したキーのラップ解除。アルゴリズムが等価性保存でない場合は、KMFBase64 入力が許可されます。対称キーラッピング/ラップ解除の暗号化を目的とした KMF 暗号化モジュールが必要です。追加のビルダーメソッド: withAlgorithm() デフォルトの入力形式:フォーマット済み:KMF 仕様に合わせてフォーマットされますデフォルトの出力形式:KMFBase64 - Base64 エンコードデフォルトの出力タイプ:文字列

この例では、モジュールglobal.sj_cmの KMFCryptoOperation オブジェクトをインスタンス化して、対称暗号化操作を実行します。グローバルアプリケーションとスコープ対象アプリケーションの両方の名前空間を含める必要があります。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION");

この例では、デフォルトの出力タイプと出力形式を更新するオプションを指定する方法を示します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION")
  .withOutputType("STRING").withOutputFormat("FORMATTED");

var cipherText=op.doOperation("hi");

この例では、統合暗号化スキーム (EC-IES) を使用して非対称暗号化操作を実行する方法を示します。signature などの長い値は、読みやすくするために切り捨てられ、省略記号に置き換えられていることに注意してください。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_ENCRYPTION")
.withInputFormat("KMFNONE")
.withOutputType("PAYLOAD");

var cipherText = op.doOperation("hi");

/*
cipherText contains an object similar to this JSON: {
  "signature": "pkg…",
  "ephemeral_key": "BDi…",
  "ciphertext": "afFS…"
}
*/

この例では、EC-IES を使用して非対称復号化操作を実行する方法を示します。

var op = new 
sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput({
  "signature": "pkg… ",
  "ephemeral_key": "BDi…"
})
.withOutputFormat("KMFNONE");

var clearText = op.doOperation("afFS…");

この例では、JWT 署名を生成および検証する方法を示します。

                                                                                         
// Validating from instance
   var moduleName = 'global.jwtimport'; // must have signature generation spec
   var header = '{ "alg": "P5512","typ": "JWT"}'; // your header JSON as a string
   var payload = '{"sub": "1234567890", "name": "John Doe", "admin": true, "iat": 1516239022)'; // your payload JSON as a string

// SIGN
   var api = new sn_kmf_ns.KMFCryptoOperation(moduleName, "JWT_SIGN").withAdditionalInput(header);
   var token = api.doOperation(payload);
   gs.info("sign = " + token);



// VERIFY
   api = new sn_kmf_ns.KMFCrypto0peration(moduleName, "JWT_VERIFY");
   var verifyoutput = api.doOperation(token);
   gs.info("verify = " + verifyOutput);

KMFCryptoOperation:doOperation(オブジェクトデータ)

指定されたデータに対して現在の KMFCryptoOperation オブジェクトによって定義された暗号化操作を実行し、結果を返します。

表 : 2. パラメーター
名前	タイプ	説明
データ	オブジェクト	関連付けられた KMFCryptoOperation オブジェクトで withSysId() ビルダーメソッドが以前に呼び出された場合を除き必須です。暗号化操作を実行する入力データ。

表 : 3. 返される内容
タイプ	説明
操作タイプによって異なります。 MAC_VERIFICATION および SIGNATURE_VERIFICATION:ブーリアンその他すべて:文字列	関連付けられた KMFCryptoOperation オブジェクトで指定された操作を実行した後のデータ結果。

この例では、 doOperation() を使用して MAC を作成します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_GENERATION"); 
var data = "aGk="; 
var mac = op.doOperation(data);

KMFCryptoOperation - withAdditionalInput(オブジェクト additionalInput)

暗号化操作の実行に必要な追加入力を設定します。

たとえば、メッセージ認証コード (MAC) の検証中に、このメソッドを使用して生成された MAC タグを渡します。同様に、署名の検証中に、署名を渡すために使用します。また、このメソッドを使用して、楕円曲線統合暗号化スキーム (EC-IES) などの統合暗号を使用して非対称操作を実行するときに、追加のデータである KMFEncryptionPayload オブジェクトを渡すこともできます。

注:

追加の入力は、KMFCryptoOperation オブジェクトで現在設定されている形式と同じである必要はありません。

表 : 4. パラメーター
名前	タイプ	説明
追加入力	文字列またはオブジェクト	オプション。EC-IES を使用する場合の非対称復号化操作を除く。KMFCryptoOperation オブジェクトで指定された暗号化操作を実行するために必要な追加の入力データ。サポートされている文字列形式: フォーマット済み:キー管理フレームワーク (KMF) の仕様に合わせてフォーマットされます。 KMFBASE64:Base64 エンコード。 KMFEncryptionPayload オブジェクト形式: `{ "ciphertext": String, "derivation_secret": String, "ephemeral_key": String, "ephemeral_key_format": String, "signature": String }`
additionalInput.ciphertext	文字列 (Base64)	非対称復号化には必要です。他のすべての操作ではオプションです。有効な値： RSA アルゴリズムを使用する場合:RSA 暗号テキスト EC-IES アルゴリズムを使用している場合:統合 AES 暗号テキスト出力タイプが payload に設定されている場合は、非対称暗号化操作から使用できます。
additionalInput.derivation_secret	文字列 (Base64)	オプション。EC-IES を使用した非対称暗号化または非対称復号化操作にのみ使用されます。統合スキームのキー導出プロセス中に使用する共有シークレット。
additionalInput.ephemeral_key	文字列 (Base64)	EC-IES を使用する場合は非対称復号化操作に必要ですが、他のすべての操作ではオプションです。統合スキームの基本合意プロセス中に使用するエフェメラル公開鍵。出力タイプが payload に設定されている場合は、非対称暗号化操作から使用できます。
additionalInput.ephemeral_key_format	文字列	オプション。EC-IES を使用した非対称暗号化または非対称復号化操作にのみ使用されます。ephemeral_key パラメーターで表される公開鍵の形式を上書きします。有効な値： x962 der
additionalInput.signature	文字列 (Base64)	EC-IES を使用した非対称復号化操作に必要で、他のすべての操作ではオプションです。統合スキームの署名検証プロセスを使用して検証する暗号テキストの署名。出力タイプが payload に設定されている場合は、非対称暗号化操作から使用できます。

表 : 5. 返される内容
タイプ	説明
なし

この例では、 withAdditionalInput() を使用して、文字列ベースの署名を KMFCryptoOperation オブジェクトに追加します。

var signature = "John Doe";
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SIGNATURE_VERIFICATION")
  .withAdditionalInput(signature);

var value = GlideStringUtil.base64Encode("Text to encode"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

この例では、 withAdditionalInput() を使用して、署名と短期キーを KMFCryptoOperation オブジェクトに追加します。doOperation() 呼び出しやpayload説明にあるような長い値は、読みやすくするために切り捨てられ、省略記号に置き換えられていることに注意してください。

var payload = new sn_kmf_ns.KMFEncryptionPayload();
payload.signature = "pkg...";
payload.ephemeral_key = " BDi...";
payload.ephemeral_key_format = "x962";

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput(payload)
  .doOperation("afFS...";

KMFCryptoOperation - withAlgorithm(文字列アルゴリズム)

折り返すキーマテリアルに関連付けられたアルゴリズムを設定します。

表 : 6. パラメーター
名前	タイプ	説明
アルゴリズム	文字列	使用するアルゴリズム。有効な値： AES:対称キータイプ EC:非対称キータイプ HMAC:対称キータイプ RSA:非対称キータイプ

表 : 7. 返される内容
タイプ	説明
なし

この例では、 withAlgorithm() を使用して、EC で使用される暗号化アルゴリズムを変更します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_WRAPPING").withAlgorithm("EC");
var value = GlideStringUtil.base64Encode("Sample key"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

KMFCryptoOperation:withInputFormat(文字列 inputFormat)

暗号化操作が実行される入力データのデータ形式を設定します。データをデコードするときに指定された形式を使用します。

表 : 8. パラメーター
名前	タイプ	説明
入力形式	文字列	入力データの形式。有効な値：フォーマット済み:キー管理フレームワーク (KMF) の仕様に合わせてフォーマットされます。 KMFBASE64:Base64 エンコード。 KMF_GLIDE_ENCRYPTER_FORMATTED:KMF 暗号化値と GlideEncrypter 暗号化値の両方の復号化をサポートします。 KMFNONE:エンコーディングなし。デフォルト:KMFCryptoOperation オブジェクトがインスタンス化されたときに指定された操作によって決定される値。詳細については、「KMFCryptoOperation:KMFCryptoOperation(文字列 cryptoModuleName, 文字列 operationName)」を参照してください。

表 : 9. 返される内容
タイプ	説明
なし

この例では、 withInputFormat() を使用して、入力形式をエンコーディングなしに変更します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION").withInputFormat("KMFNone");
var result = op.doOperation("Text with no encoding"); // Pass in unencrypted String

この例では、 withInputFormat() を使用して入力形式を KMF_GLIDE_ENCRYPTER_FORMATTED に変更します。

var encryptOp = new sn_kmf_ns.KMFCryptoOperation("<module_name>", "SYMMETRIC_DECRYPTION")
 .withInputFormat("KMF_GLIDE_ENCRYPTER_FORMATTED")
 .withOutputFormat("KMFNone"); 

var clear_text = encryptOp.doOperation(<encrypted_text>);

KMFCryptoOperation - withOutputFormat(文字列 outputFormat)

暗号化操作によって返される出力データのデータ形式を設定します。データをエンコードするときに指定された形式を使用します。

表 : 10. パラメーター
名前	タイプ	説明
outputFormat	文字列	出力データの形式。有効な値：フォーマット済み:キー管理フレームワーク (KMF) の仕様に合わせてフォーマットされます。 KMFBASE64:Base64 エンコード。 KMFNONE:デコードなし。MAC_VERIFICATION と SIGNATURE_VERIFICATION でのみサポートされています。このメソッドが呼び出されない場合のデフォルト:KMFCryptoOperation オブジェクトがインスタンス化されたときに指定された操作によって決定される値。詳細については、「KMFCryptoOperation:KMFCryptoOperation(文字列 cryptoModuleName, 文字列 operationName)」を参照してください。

表 : 11. 返される内容
タイプ	説明
なし

この例では、 withOutputFormat() を使用して復号化の出力形式を KMFNone (デフォルトは KMFBase64) に設定します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_DECRYPTION").withOutputFormat("KMFNone");
var clear_data = op.doOperation(<FORMATTED_data>); // Pass in default of FORMATTED data

KMFCryptoOperation - withOutputType(String outputType)

暗号化操作の実行後に返される出力データのデータタイプを設定します。

注:

MAC_VERIFICATIONまたはSIGNATURE_VERIFICATION操作の KMFCryptoOperation オブジェクトをインスタンス化する場合、ブール値を渡してこのメソッドを呼び出して正しい出力型を設定する必要があります。そうしないと、操作の実行時に例外がスローされます。

表 : 12. パラメーター
名前	タイプ	説明
出力タイプ	文字列	出力データのタイプ。すべての操作にすべての出力タイプを適用できるわけではありません。サポートされていないタイプの場合は、例外がスローされます。有効な値 (値の大文字と小文字を区別しない)：文字列: MAC_VERIFICATION または SIGNATURE_VERIFICATION 操作には無効です。ブーリアン: MAC_VERIFICATION または SIGNATURE_VERIFICATION 操作にのみ有効です。ペイロード: ASYMMETRIC_ENCRYPTION 操作に対してのみ有効です。この出力タイプは EC-IES に使用します。注: `Payload` の出力を指定する場合、doOperation() メソッドの出力は KMFEncryptionPayload オブジェクトです。このオブジェクトの構造の詳細については、「 withAdditionalInput()」を参照してください。デフォルト:KMFCryptoOperation オブジェクトがインスタンス化されたときに指定された、操作によって決定される値。詳細については、「KMFCryptoOperation:KMFCryptoOperation(文字列 cryptoModuleName, 文字列 operationName)」を参照してください。

表 : 13. 返される内容
タイプ	説明
なし

この例では、 withOutputType() を使用して MAC_VERIFICATION の出力タイプをブールに設定します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_VERIFICATION")
  .withOutputType("Boolean").withAdditionalInput(<MAC>);
var value = GlideStringUtil.base64Encode("Text to sign"); // Default input type is KMFBase64
var result = op.doOperation(String(value));

KMFCryptoOperation:withSysId(文字列 sysId)

KMFCryptoOperation オブジェクトで折り返すキーのsys_idを設定します。キーの対称および非対称のラッピングに適用できます。

表 : 14. パラメーター
名前	タイプ	説明
sysId	文字列	ラップするキーのSys_id。テーブル:モジュールキー [sys_kmf_module_key]

表 : 15. 返される内容
タイプ	説明
なし

この例では、 withSysId() を使用してラップするキーを定義します。

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_WRAPPING").withSysId("0d06ce525b231010f86d1b341d81c777");
var wrappedKey = operation.doOperation(); // No need to pass data when using withSysId()