{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":41717,"path":"platform-security/now-platform-encryption.md","title":"Field Encryption Enterprise","bundle":null,"doc_type":null,"release":"australia","body":"\n# Field Encryption Enterprise\n\nField Encryption Enterprise uses the Key Management Framework \\(KMF\\) to enable you to customize and manage how fields and attachments are encrypted and decrypted on your instance. A subscription is required to use Field Encryption Enterprise.\n\n**Important:** This topic covers the enterprise version of Field Encryption. For information on the standard version of Field Encryption, or to learn the differences between the two versions, see [Exploring Field Encryption](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/exploring-fe.md).\n\nField Encryption Enterprise is premised with Field Encryption and uses the Key Management Framework and its full support of key management functions. Field Encryption Enterprise provides key-protection and key life-cycle management for application-level field encryption. All keys are protected with a key-wrapping hierarchy ultimately rooted in FIPS \\(Federal Information Processing Standards\\) 140-2-L3 Hardware Security Modules \\(HSM\\).\n\nField Encryption Enterprise gives you the ability to manage how supported fields are encrypted and decrypted in accordance with [NIST 800-57](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf) practices. It also uses the most updated version of field-level encryption, including integration for proper key protection and management.\n\nSpecifically, Field Encryption Enterprise uses the KMF encryption modules, granting you more control of server-side encryption. KMF verifies proper data encryption key protection using key hierarchy and envelope encryption. Your instance encrypts data through cryptographic modules that you configure. You can create an access policy for each module then configure cryptographic specifications and access policies and control key life-cycle management control.\n\nField Encryption Enterprise supports module access policies based on:\n\n-   Scope\n-   Role\n-   Script\n-   Resource Exchange\n-   System User\n\nSee [Create a module access policy](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/create-module-access-policy.md) for additional information.\n\n**Note:** For details on the supported features of Field Encryption and how to upgrade and subscribe to the Field Encryption Enterprise entitlement refer to [Encryption and Key Management subscription bundle](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/encryption-sku.md).\n\n## Encryption terms\n\n<table id=\"table_ddr_sgb_54b\"><thead><tr><th>\n\nTerm\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n\\[Omitted image \"keys-on-ring-2.png\"\\] Alt text: Key management\\\\\n\n</td><td>\n\nSupport for key managementFundamental to Field Encryption Enterprise is the Key Management Framework \\(KMF\\).\n\n Gain the following capabilities:\n\n-   Key life-cycle management.\n-   Key rotation. See [Rotate keys](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/rotate-cust-supplied-keys.md) for details.\n-   Key protection and key generation with FIPS 140-2-L3 Hardware Security Modules \\(HSMs\\).\n-   Segregation of roles and duties.\n-   The secure transfer of data encryption keys between instances, such as production and non-production instances.\n-   Customer Supplied Keys \\(CSK\\) with key-wrapping.\n-   Non-deterministic encryption.\n-   Mass encryption/decryption.\n-   Auditing of key access/use.\n\n See [Key Management Framework Reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/understanding-kmf.md) for details.\n\n</td></tr><tr><td>\n\n\\[Omitted image \"keys-on-ring-csk-icon-2.png\"\\] Alt text: Customer-supplied key\n\n</td><td>\n\nSupport for customer supplied keysOne of the biggest benefits of Field Encryption Enterprise is that you can use your own keys for encryption. Administrators have the choice to use ServiceNow supplied keys or your own customer-supplied keys \\(CSK\\) for encryption on the ServiceNow AI Platform®.\n\n You can also manage the key life cycle and decide when to revoke, rotate, and inactivate the keys. After you enable customer-supplied keys and create a cryptographic module, you download a token and public ephemeral key. You use the token and public key to wrap your key and then upload to the instance. To use customer-supplied keys, see [Configure field encryption settings to select key type](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/configure-field-encryption-settings.md) and [Using customer-supplied keys with Field Encryption Enterprise](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/csk-landing.md).\n\n</td></tr><tr><td>\n\n\\[Omitted image \"lock-locked-2.png\"\\] Alt text: Field Encryption\n\n</td><td>\n\nSupport for both field encryption and attachment encryptionBoth field encryption and attachment encryption use cryptographic modules and access policies through Encrypted Field Configurations. The Encrypted Field Configuration form is used to choose an encryption type of column or attachment encryption. See [Set encrypted field configurations](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/set-encrypted-field-config.md) for more information and supported field types.\n\n</td></tr><tr><td>\n\n\\[Omitted image \"non-deterministic-encryption-2.png\"\\] Alt text: Non-deterministic encryption\n\n</td><td>\n\nSupport for non-deterministic encryptionField Encryption Enterprise supports non-deterministic encryption for enhanced security. If the system encrypts the same data more than once, the ciphertexts are different each time. Non-deterministic encryption is available with Advanced Encryption Standard \\(AES\\) encryption with Cipher Block Chaining \\(CBC\\).\n\n You can enable this feature through the Equality Preserving option on the Algorithm Definition stage of the cryptographic specification. Create a cryptographic specification for a crypto module and define an algorithm for encryption and generate the key.\n\n See [Create a cryptographic module](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/create-cryptographic-module.md) to define the mechanisms used for cryptographic operations and for more information on enabling non-deterministic encryption.\n\n</td></tr><tr><td>\n\n\\[Omitted image \"resource-exchange-2.png\"\\] Alt text: Resource Exchange\n\n</td><td>\n\nResource Exchange Field Encryption Enterprise keys instance to instance in a secure manner using the KMF cryptographic APIs to provide confidentiality, integrity, authentication, and non-repudiation. Resource Exchange is a KMF feature that gives you the capability to exchange resources between instances in a secure manner. See [Key Management Framework Resource Exchange](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/platform-encryption/resource-exchange.md) for details.\n\n</td></tr></tbody>\n</table>**Note:** If you choose not to activate Field Encryption Enterprise, you can still use Field Encryption. See [Exploring Field Encryption](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/exploring-fe.md) for information.\n\nField Encryption Enterprise supports on-premise customers. It doesn’t support Domain Separation.\n\n## Support for additional encrypted fields\n\nThe standard version of Field Encryption is limited to five encrypted columns. Field Encryption Enterprise supports an unlimited number of encrypted columns.\n\n## Attachment Encryption\n\n-   **Attachment encryption by default**\n\n    Customers using Field Encryption have attachments encrypted by default in tables that have an active Encrypted Field Configuration \\(EFC\\) type of **Attachment**.\n\n    This default encryption defined by the EFC configuration means that it's not necessary for admins to manually declare that an attachment should be encrypted on upload for these tables.\n\n-   **Administrators can disallow users from attaching unencrypted files**\n\n    For details, see [Prevent users from attaching unencrypted files](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/attach-enc-property.md).\n\n-   **Opt out of default encryption**\n\n    If you don’t want attachments encrypted by default based on EFC configuration, you can opt out of this option by contacting ServiceNow support.\n\n    To opt out of this feature, create a support case with ServiceNow support, and include this statement in a comment on the case record:\n\n    `\"I [customer name], understand that I am asking ServiceNow to turn off a recommended security best practice for attachments, and that [customer company] assumes any additional risk related to their configuration and use of unencrypted attachments in the ServiceNow application.\"`\n\n\n## API support\n\nField Encryption Enterprise enables the following APIs.\n\n**Note:** The API behavior described in the following table represents the default configuration for the latest base system package. If you're working with older package versions, you may experience different functionality.\n\n<table id=\"table_jns_p3m_mhc\"><thead><tr><th>\n\nAPI\n\n</th><th>\n\nDescription\n\n</th><th>\n\nParameters\n\n</th><th>\n\nReturn type\n\n</th></tr></thead><tbody><tr><td>\n\n``changeEncryptionContext()``\n\n</td><td>\n\nUpdates an active Encryption Context \\(EC\\) used to encrypt an attachment. When CLE is enabled with the CLE Starter plugin using KMF Crypto Module \\(CM\\), the API locates the CM for the EC and uses it to encrypt the attachment.\n\n**Note:** This API is only available in the Global scope.\n\n</td><td>\n\n-   sourceTable – Name of table that has the attachment.\n-   sourceID – Table record system id.\n-   attachmentID – The sys\\_attachment record system id.\n-   newEncryptionContextID - System ID of the new context.\n\n</td><td>\n\nBoolean\n\n</td></tr><tr><td>\n\n`changeCryptoModule()`\n\n</td><td>\n\nUpdates an active encryption module used to encrypt an attachment.**Note:** This API is only available in the Global scope.\n\n</td><td>\n\n-   sourceTable – Name of table that has the attachment.\n-   sourceID – Table record system id.\n-   attachmentID – The sys\\_attachment record system id.\n-   newCryptoModuleId - System ID of the new encryption module to encrypt the attachment.\n\n</td><td>\n\nBoolean\n\n</td></tr><tr><td>\n\n`disableEncryption()`\n\n</td><td>\n\nDisable active encryption on an attachment.\n\n</td><td>\n\n-   sourceTable – Name of table that contains the attachment.\n-   sourceID – Table record system id.\n-   attachmentID – The sys\\_attachment record system id.\n\n</td><td>\n\nBoolean\n\n</td></tr><tr><td>\n\n`getDisplayValue()`\n\n</td><td>\n\nReturns the cleartext display value of an encrypted field.\n\n</td><td>\n\n \n\n</td><td>\n\nString\n\n</td></tr><tr><td>\n\n`getValue()`\n\n</td><td>\n\nReturns the cleartext value of an ecrypted field when glide\\_encryption.set\\_value\\_support\\_cle.disabled is false \\(requires Module Access Policy \\(MAP\\)\\). Returns the encrypted value of an encrypted field when glide\\_encryption.set\\_value\\_support\\_cle.disabled is true.\n\n</td><td>\n\n \n\n</td><td>\n\nString\n\n</td></tr><tr><td>\n\n`setDisplayValue()`\n\n</td><td>\n\nInserts encrypted data into an encrypted field for display purposes.\n\n</td><td>\n\n-   name – Field name.\n-   value – Field value.\n\n</td><td>\n\nBoolean\n\n</td></tr><tr><td>\n\n`setValue()`\n\n</td><td>\n\nInserts encrypted data into an encrypted field, controlled by a system property. Encrypts data when glide\\_encryption.set\\_value\\_support\\_cle.disabled is false \\(requires MAP\\); writes unencrypted data when set to true \\(no MAP required\\), when glide\\_encryption.set\\_value\\_support\\_cle.disabled is true.\n\n</td><td>\n\n-   name – Field name.\n-   value – Field value.\n\n</td><td>\n\nBoolean\n\n</td></tr></tbody>\n</table>The following script illustrates API changes when the Incident short description is encrypted:\n\n```\n\nvar gr = new GlideRecord('incident'); //creates a new incident\ngr.setValue('short_description','test123'); //sets the value to **test123**\nvar sys_ID = gr.insert(); //inserts the record in the Incident table.\ngs.info(gr.getValue('short_description')); //displays the unencrypted value\n\n```\n\nWhen the Field Encryption plugin is installed, `glide_encryption.set_value_support_cle.disabled` is set to false by default.\n\nWhen you call `getValue()` on an encrypted text field, it returns the plaintext if you have access to the cryptographic module; otherwise, it returns either the ciphertext or `null`.\n\n**Parent Topic:**[Exploring Field Encryption](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/platform-security/exploring-fe.md)\n\n"}}