---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# KMFCryptoOperation - Scoped, Global

# KMFCryptoOperation - Scoped, Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 11 minutes to read

The KMFCryptoOperation class provides methods for performing cryptographic operations using a Key Management Framework (KMF) cryptographic module or a Column Level Encryption encryption module.

To use this API, you must have already created and configured a KMF cryptographic module or a CLE encryption module. The module must have one or more cryptographic specifications and you must create or import its associated key.
For details, see [Cryptographic modules](https://www.servicenow.com/docs/access?context=crypto-module-overview&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US).

The KMFCryptoOperation object generated using this API represents a cryptographic operation,
such as a Symmetric Encryption. Use the KMFCryptoOperations() method to
create this object, the builder methods to set properties on the object, and the
doOperation() method to execute the operation.

You can use this API in both scoped and global applications. You must always specify the
`sn_kmf_ns` namespace when calling this API.

## KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName) {#ariaid-title2}

Creates a KMFCryptoOperation object for the specified module and operation.
This API leverages builder methods. Builder methods update properties on the
KMFCryptoOperation object, such as changing the desired output format of the data. Not all
builder methods are valid for all operations. The builder methods available for each
operation are noted in the parameters table below.  
The following builder methods are valid for all operation types:

* [withInputFormat()](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withInputFormat_S "Sets the data format for the input data on which the cryptographic operation will be performed. Uses the specified format when decoding the data.")
* [withOutputFormat()](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withOutputFormat_S "Sets the data format of the output data that is returned by the cryptographic operation. Uses the specified format when encoding the data.")
* [withOutputType()](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withOutputType_S "Sets the data type for the output data returned after the cryptographic operation is performed.")
{#KMFCO-KMFCryptoOperation_S_S__ul_ijl_xtb_wnb}  
Important:  
Base64 input values used in this document must be URL safe (contains only A-Z, a-z, 0-9, dash( - ) and underscore( _ ) characters). {#KMFCO-KMFCryptoOperation_S_S__table_mth_p3t_tnb__entry__3}

| Name | Type | Description |
|-|-|-|
| cryptoModuleName | String | Name of the Key Management Framework (KMF) cryptographic module or Column Level Encryption encryption module to use. You must create the module before calling this method. For details, see [Cryptographic module overview](https://www.servicenow.com/docs/access?context=crypto-module-overview&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US). |
| operationName | String | Name of the operation to perform. Valid values (not case-sensitive): * ASYMMETRIC_DECRYPTION: Data decryption using an asymmetric-key algorithm. Requires a KMF cryptographic module with an Asymmetric Data Decryption cryptographic purpose. * Additional builder methods: withAdditionalInput() * Default input format: Formatted - Formatted to the KMF specifications * Default output format: KMFBase64 - Base64 encoded * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_jzh_zsb_wnb} * ASYMMETRIC_ENCRYPTION: Data encryption using an asymmetric-key algorithm. Requires a KMF cryptographic module with an Asymmetric Data Encryption cryptographic purpose. * Additional builder methods: withAdditionalInput() * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String . Output can also be an [KMFEncryptionPayload](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withAddInput_S__KMFEncryptionPayload) object. RSA and EC-IES are compatible with both. For additional information on the KMFEncryptionPayload object, see [withAdditionalInput()](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withAddInput_S__KMFEncryptionPayload). {#KMFCO-KMFCryptoOperation_S_S__ul_qtb_hvb_wnb} * ASYMMETRIC_UNWRAPPING: Key unwrapping using an asymmetric-key algorithm. Requires a KMF cryptographic module with an Asymmetric Key Unwrapping cryptographic purpose. * Additional builder methods: withAlgorithm() * Default input format: Formatted - Formatted to the KMF specifications * Default output format: KMFBase64 - Base64 encoded * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_t2c_pvb_wnb} * ASYMMETRIC_WRAPPING: Key wrapping using an asymmetric-key algorithm. Requires a KMF cryptographic module with an Asymmetric Key Wrapping cryptographic purpose. * Additional builder methods: withAlgorithm(), withSysId() * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String * MAC_GENERATION: Generation of a Message Authentication Code (MAC). Symmetric-key algorithm based to provides data integrity and authentication. Requires a KMF cryptographic module with a Symmetric Authenticity cryptographic purpose. * Additional builder methods: None * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String * MAC_VERIFICATION: Verification of a MAC. Symmetric-key algorithm based to provide data integrity and authentication. Requires a KMF cryptographic module with a Symmetric Authenticity cryptographic purpose. * Additional builder methods: withAdditionalInput() * Default input format: KMFBase64 - Base64 encoded * Default output format: KMFNone - No decoding * Default output type: Boolean {#KMFCO-KMFCryptoOperation_S_S__ul_xqh_bxb_wnb} * SIGNATURE_GENERATION: Generation of a digital signature. Asymmetric-key algorithm based to provide data integrity and authentication. Requires a KMF cryptographic module with a Signature Generation cryptographic purpose. * Additional builder methods: None * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_t5k_gtj_wnb} * SIGNATURE_VERIFICATION: Verification of a digital signature. Asymmetric-key algorithm based to provide data integrity and authentication. Requires a KMF cryptographic module with a Signature Verification cryptographic purpose. * Additional builder methods: withAdditionalInput() * Default input format: KMFBase64 - Base64 encoded * Default output format: KMFNone - No decoding * Default output type: Boolean {#KMFCO-KMFCryptoOperation_S_S__ul_cvk_gtj_wnb} * SYMMETRIC_ENCRYPTION: Data encryption using a symmetric-key algorithm. If the algorithm is not equality preserving, only formatted output is allowed. Requires a KMF cryptographic module with a Symmetric Data Encryption/Decryption cryptographic purpose. * Additional builder methods: None * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_vg3_ryb_wnb} * SYMMETRIC_DECRYPTION: Data decryption using a symmetric-key algorithm. If the algorithm is not equality preserving, KMFBase64 input is allowed. Requires a KMF cryptographic module with a Symmetric Data Encryption/Decryption cryptographic purpose. * Additional builder methods: None * Default input format: Formatted - Formatted to the KMF specifications * Default output format: KMFBase64 - Base64 encoded * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_mcx_2tj_wnb} * SYMMETRIC_WRAPPING: Key wrapping using a symmetric-key algorithm. If the algorithm is not equality preserving, only formatted output is allowed. Requires a KMF cryptographic module with a Symmetric Key Wrapping/Unwrapping cryptographic purpose. * Additional builder methods: withAlgorithm() and withSysId() * Default input format: KMFBase64 - Base64 encoded * Default output format: Formatted - Formatted to the KMF specifications * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_sz2_xyb_wnb} * SYMMETRIC_UNWRAPPING: Key unwrapping using a symmetric-key algorithm. If the algorithm is not equality preserving, KMFBase64 input is allowed. Requires a KMF cryptographic module with a Symmetric Key Wrapping/Unwrapping cryptographic purpose. * Additional builder methods: withAlgorithm() * Default input format: Formatted - Formatted to the KMF specifications * Default output format: KMFBase64 - Base64 encoded * Default output type: String {#KMFCO-KMFCryptoOperation_S_S__ul_yh4_tyb_wnb} |
[Table 1. Parameters]

{#KMFCO-KMFCryptoOperation_S_S__table_mth_p3t_tnb}  
This example instantiates a KMFCryptoOperation object for the module global.sj_cm to
perform a Symmetric Encryption operation. You must include the namespace for both global and
scoped applications.

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

This example shows how to specify options to update the default output type and output
format.

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

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

This example shows how to perform an Asymmetric Encryption operation using an Integrated
Encryption Scheme (EC-IES). Note that long values, such as signature,
have been truncated and replaced with an ellipse for readability.

    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..."
    }
    */

This example shows how to perform an Asymmetric Decryption operation using 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...");

## KMFCryptoOperation - doOperation(Object data) {#ariaid-title3}

Performs the cryptographic operation defined by the current KMFCryptoOperation object
on the supplied data and returns the result.
{#KMFCO-doOperation_O__table_sh4_4sl_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| data | Object | Required except if the withSysId() builder method has previously been called on the associated KMFCryptoOperation object. Input data on which to perform the cryptographic operation. |
[Table 2. Parameters]

{#KMFCO-doOperation_O__table_sh4_4sl_vnb} {#KMFCO-doOperation_O__table_th4_4sl_vnb__entry__2}

| Type | Description |
|-|-|
| Depends on the operation type. * MAC_VERIFICATION and SIGNATURE_VERIFICATION: Boolean * All others: String {#KMFCO-doOperation_O__ul_dzf_jpj_wnb} | Data results after performing the operation specified in the associated KMFCryptoOperation object. |
[Table 3. Returns]

{#KMFCO-doOperation_O__table_th4_4sl_vnb}  
This example uses the doOperation() to create a MAC.

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

## KMFCryptoOperation - withAdditionalInput(Object additionalInput) {#ariaid-title4}

Sets the additional input needed to perform the cryptographic operation.
For example, during a Message Authentication Code (MAC) verification, use this method to
pass in the generated MAC tag. Similarly, during signature verification, use it to pass in
the signature. You can also use this method to pass additional data, a KMFEncryptionPayload
object, when performing an asymmetric operation with an integrated cipher, such as Elliptic
Curve Integrated Encryption Scheme (EC-IES.)  
Note:  
The additional input does not have to be in the same format that is currently set on the KMFCryptoOperation object. {#KMFCO-withAddInput_S__table_exs_fhl_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| additionalInput | String or Object | Optional, except for Asymmetric Decryption operations when using EC-IES. Additional input data needed to perform the cryptographic operation specified in the KMFCryptoOperation object. Supported string formats: * FORMATTED: Formatted to the Key Management Framework (KMF) specifications. * KMFBASE64: Base64 encoded. {#KMFCO-withAddInput_S__ul_pyr_sml_vnb} KMFEncryptionPayload object format:{#KMFCO-withAddInput_S__KMFEncryptionPayload} { "ciphertext": String, "derivation_secret": String, "ephemeral_key": String, "ephemeral_key_format": String, "signature": String } |
| additionalInput.ciphertext | String (Base64) | Required for Asymmetric Decryption, optional for all other operations. Valid values: * If using an RSA algorithm: RSA ciphertext * If using an EC-IES algorithm: Integrated AES ciphertext Available from the Asymmetric Encryption operation when the output type is set to payload. |
| additionalInput.derivation_secret | String (Base64) | Optional, only used for the Asymmetric Encryption or Asymmetric Decryption operations with EC-IES. Shared secret to use during the key derivation process of the integrated scheme. |
| additionalInput.ephemeral_key | String (Base64) | Required for the Asymmetric Decryption operation when using EC-IES, optional for all other operations. Ephemeral public key to use during the basic agreement process of the integrated scheme. Available from the Asymmetric Encryption operation when the output type is set to payload. |
| additionalInput.ephemeral_key_format | String | Optional, only used for the Asymmetric Encryption or Asymmetric Decryption operations with EC-IES. Overrides the format of the public key represented by the ephemeral_key parameter. Valid values: * x962 * der {#KMFCO-withAddInput_S__ul_kyp_vrg_1qb} |
| additionalInput.signature | String (Base64) | Required for the Asymmetric Decryption operation with EC-IES, optional for all others. The signature of the ciphertext to validate using the signature verification process of the integrated scheme. Available from the Asymmetric Encryption operation when the output type is set to payload. |
[Table 4. Parameters]

{#KMFCO-withAddInput_S__table_exs_fhl_vnb} {#KMFCO-withAddInput_S__table_fxs_fhl_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 5. Returns]

{#KMFCO-withAddInput_S__table_fxs_fhl_vnb}  
This example uses withAdditionalInput() to add a string-based signature
to the KMFCryptoOperation object.

    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));

This example uses withAdditionalInput() to add a signature and ephemeral
key to the KMFCryptoOperation object. Note that long values, such as those in the
doOperation() call and payload description, have
been truncated and replaced with an ellipse for readability.

    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(String algorithm) {#ariaid-title5}

Sets the algorithm associated with the key material to wrap.
{#KMFCO-withAlgorithm_S__table_kx1_r4l_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| algorithm | String | Algorithm to use. Valid values: * AES: Symmetric key type * EC: Asymmetric key type * HMAC: Symmetric key type * RSA: Asymmetric key type |
[Table 6. Parameters]

{#KMFCO-withAlgorithm_S__table_kx1_r4l_vnb} {#KMFCO-withAlgorithm_S__table_lx1_r4l_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 7. Returns]

{#KMFCO-withAlgorithm_S__table_lx1_r4l_vnb}  
This example uses withAlgorithm() to change the encryption algorithm
used to 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(String inputFormat) {#ariaid-title6}

Sets the data format for the input data on which the cryptographic operation will be
performed. Uses the specified format when decoding the data.
{#KMFCO-withInputFormat_S__table_lvd_kxk_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| inputFormat | String | Format of the input data. Valid values: * FORMATTED: Formatted to the Key Management Framework (KMF) specifications. * KMFBASE64: Base64 encoded. * KMF_GLIDE_ENCRYPTER_FORMATTED: Support decryptions of both KMF encrypted values and GlideEncrypter encrypted values. * KMFNONE: No encoding. Default: Value determined by the operation specified when the KMFCryptoOperation object was instantiated. For more information, see [KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName)](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-KMFCryptoOperation_S_S "Creates a KMFCryptoOperation object for the specified module and operation."). |
[Table 8. Parameters]

{#KMFCO-withInputFormat_S__table_lvd_kxk_vnb} {#KMFCO-withInputFormat_S__table_mvd_kxk_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 9. Returns]

{#KMFCO-withInputFormat_S__table_mvd_kxk_vnb}  
This example uses withInputFormat() to change the input format to have
no encoding.

    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

This example uses withInputFormat() to change the input format to 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(String outputFormat) {#ariaid-title7}

Sets the data format of the output data that is returned by the cryptographic
operation. Uses the specified format when encoding the data.
{#KMFCO-withOutputFormat_S__table_ezl_gdl_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| outputFormat | String | Format of the output data. Valid values: * FORMATTED: Formatted to the Key Management Framework (KMF) specifications. * KMFBASE64: Base64 encoded. * KMFNONE: No decoding. Only supported for MAC_VERIFICATION and SIGNATURE_VERIFICATION. Default if this method is not called: Value determined by the operation specified when the KMFCryptoOperation object was instantiated. For more information, see [KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName)](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-KMFCryptoOperation_S_S "Creates a KMFCryptoOperation object for the specified module and operation."). |
[Table 10. Parameters]

{#KMFCO-withOutputFormat_S__table_ezl_gdl_vnb} {#KMFCO-withOutputFormat_S__table_fzl_gdl_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 11. Returns]

{#KMFCO-withOutputFormat_S__table_fzl_gdl_vnb}  
This example uses withOutputFormat() to set the output format of the
decryption to KMFNone (default is 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) {#ariaid-title8}

Sets the data type for the output data returned after the cryptographic operation is
performed.
Note:  
When you instantiate the KMFCryptoOperation object for MAC_VERIFICATION or SIGNATURE_VERIFICATION operations, you must also call this method, passing boolean, to set the correct output type or an exception is thrown when you execute the operation. {#KMFCO-withOutputType_S__table_h5z_31l_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| outputType | String | Type of output data. Not all output types are applicable to all operations. For an unsupported type, an exception is thrown. Valid values (not case-sensitive): * String: Not valid for MAC_VERIFICATION or SIGNATURE_VERIFICATION operations. * Boolean: Only valid for MAC_VERIFICATION or SIGNATURE_VERIFICATION operations. * Payload: Only valid for the ASYMMETRIC_ENCRYPTION operation. Use this output type for EC-IES. Note: When specifying an output of <kbd class="ph userinput">Payload</kbd>, the output of the doOperation() method is a KMFEncryptionPayload object. For more information on the structure of this object, see [withAdditionalInput()](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-withAddInput_S__KMFEncryptionPayload). Default: Value determined by the operation, specified when the KMFCryptoOperation object was instantiated. For more information, see [KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName)](https://servicenow-prod.fluidtopics.net/GD2TA_qptcif_UcXgJTB~w#KMFCO-KMFCryptoOperation_S_S "Creates a KMFCryptoOperation object for the specified module and operation."). |
[Table 12. Parameters]

{#KMFCO-withOutputType_S__table_h5z_31l_vnb} {#KMFCO-withOutputType_S__table_i5z_31l_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 13. Returns]

{#KMFCO-withOutputType_S__table_i5z_31l_vnb}  
This example uses withOutputType() to set the output type for
MAC_VERIFICATION to Boolean.

    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(String sysId) {#ariaid-title9}

Sets the sys_id of the key to wrap on the KMFCryptoOperation object. Applicable to
symmetric and asymmetric wrapping of keys.
{#KMFCO-withSysId_S__table_ymp_jnl_vnb__entry__3}

| Name | Type | Description |
|-|-|-|
| sysId | String | Sys_id of the key to wrap. Located in the Module Key \[sys_kmf_module_key\] table. |
[Table 14. Parameters]

{#KMFCO-withSysId_S__table_ymp_jnl_vnb} {#KMFCO-withSysId_S__table_zmp_jnl_vnb__entry__2}

| Type | Description |
|-|-|
| None |   |
[Table 15. Returns]

{#KMFCO-withSysId_S__table_zmp_jnl_vnb}  
This example uses withSysId() to define the key to wrap.

    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()