Encryption scripting examples

These example scripts show you how to accomplish common encryption tasks.

Encrypt unencrypted attachments

The following sample script encrypts unencrypted attachments, such as in the incident table.

Note: Impersonation does not change the encryption contexts available to a user. Even while impersonating, you have only the encryption contexts available to you originally.
bulkEncryption();
 
  function bulkEncryption() {
	gs.log("*********** BULK ENCRYPTION RUN BY " + gs.getUserName());
	encryptAttachments("incident", "testContext");
	gs.log("*********** BULK ENCRYPTION COMPLETED");
  }
 
  // Note that whomever runs this script must have access to use the specified encryption context or nothing will happen when 
  // "changeEncryptionContext" is called except that a warning will appear in the log: WARNING *** WARNING *** Attempt to get 
  // cipher for encryption context 'contextName' without authorization
  function encryptAttachments(table, encryptionContextName) {
	var contextGR = new GlideRecord("sys_encryption_context");
	contextGR.addQuery("name", encryptionContextName);
	contextGR.query();
	if (!contextGR.next()) {
		gs.log("*********** No such encryption context " + encryptionContextName);
		return 0;
	}
 
	var encryptionId = contextGR.getUniqueValue();
 
	gs.log("*********** BEGIN ENCRYPTING ATTACHMENTS FOR " + table + " TABLE");
	var attachmentGR = new GlideRecord("sys_attachment");
	attachmentGR.addQuery("table_name", table); // only attachments for the specified table
	attachmentGR.addNullQuery("encryption_context"); // only attachments not yet encrypted
	attachmentGR.query();
	var count = 0;
	while (attachmentGR.next()) {
		var sysAttachment = new GlideSysAttachment();
		sysAttachment.changeEncryptionContext(attachmentGR.getValue("table_name"), attachmentGR.getValue("table_sys_id"), 
			attachmentGR.sys_id, encryptionId);
		gs.log("*********** ENCRYPTED [" + attachmentGR.sys_id + "] " + attachmentGR.getValue("file_name"));
		count++;
	}
	gs.log("*********** ENCRYPTED " + count + " ATTACHMENTS FOR " + table + " TABLE");
	return count;
  }

To write a script changing the encryption context from one context to another, access to both contexts is required.

Set the encryption context ID

The function setContextID is provided to set the encryption context ID of an encrypted field in script.

The argument to the function is the sys_id of the encryption context you wish to use. The following example creates records with an encrypted field, u_subspecies, encrypted by the "Species Security" encryption context.

Note: The user who runs this script must have access to the encryption context.
encrypt();
 
function encrypt() {
  var encryptionID = getEncryptionID("Species Security");
  if (encryptionID == "")
     return;
 
   createEncryptedRecord("Sumatran tiger", "Panthera", "tigris", "sumatrae", encryptionID);
   createEncryptedRecord("Bengal tiger", "Panthera", "tigris", "tigris", encryptionID);
   createEncryptedRecord("Siberian tiger", "Panthera", "tigris", "altaica", encryptionID);
}
 
function getEncryptionID(encryptionName) {
   var contextGR = new GlideRecord("sys_encryption_context");
   contextGR.addQuery("name", encryptionName);
   contextGR.query();
   if (!contextGR.next()) {
      gs.log("*********** No such encryption context " + encryptionContextName);
      return "";
   }
   return contextGR.getUniqueValue();
}
 
function createEncryptedRecord(commonName, genus, species, subspecies, encryptionID) { 
   var newRecord = new GlideRecord("u_species_encrypted");
   newRecord.u_common_name = commonName;
   newRecord.u_genus = genus;
   newRecord.u_species = species;
 
   // We have one encrypted field, u_subspecies. 
   newRecord.u_subspecies.setDisplayValue(subspecies);
   newRecord.u_subspecies.setContextID(encryptionID); // use our encryption context for the field
 
   newRecord.insert();
}

Remove encryption contexts

These functions remove an encryption context, or all encryption contexts, from those available to the user session.

This can be used by customers in a script to further limit the encryption contexts that are available to a user under certain conditions. For example, a synchronous Script Action triggered by the session.established event could remove all encryption contexts if a user was not connecting from an IP in a certain range.

if (some condition) {
   var contexts = gs.getSession().getEncryptionContext();
   contexts.removeAllContexts();
}

Individual encryption contexts can be removed as well using the sys_id of the encryption context.

if (some condition) {
   var contexts = gs.getSession().getEncryptionContext();
   contexts.removeContext("077d9b3307211000e2bb5720e1021e61");
}

Return a decrypted field value

You can return the field value for an encrypted field by using the getDisplayValue method.