security methods

chooseRecipientsDialog

chooseSecurityPolicy

exportToFile

getHandler

getSecurityPolicies

importFromFile

importSettings

chooseRecipientsDialog

Opens a dialog box that allows a user to choose a list of recipients. Returns an array of generic Group objects that can be used when encrypting documents or data using either encryptForRecipients or addRecipientListCryptFilter methods of the Doc.

Note:Can be executed only during a console, menu, or application initialization event. See Privileged versus non-privileged context for details.

Parameters

Returns

An array of Group objects.

See the Doc encryptForRecipients method for a description of the Group object.

DisplayOptions object

The DisplayOptions object contains the following properties.

Example 1

Retrieve groups with permissions

   var oOptions = {

      bAllowPermGroups: true,

      bPlaintextMetadata: false,

      cTitle: "Encrypt and Email",

      cNote: "Select recipients",

      bAllowImportFromFile: false,

      bRequireEncryptionCert: true,

      bRequireEmail: true

   };

   var groupArray = security.chooseRecipientsDialog( oOptions );

   console.println("Full name = " + groupArray[0].userEntities[0].fullName);

Example 2

Get a list of recipients for which to encrypt data and email the document.

   var oOptions = { bAllowPermGroups: false,

      cNote: "Select the list of recipients. "

      + "Each person must have both an email address and a certificate.",

      bRequireEmail: true,

      bUserCert: true

   };

   var oGroups = security.chooseRecipientsDialog( oOptions );

   // Display the list of recipients in an alert

   // Build an email "to" mailList

   var numCerts = oGroups[0].userEntities.length;

   var cMsg = "The document will be encrypted for the following:\n";

   var mailList = new Array;

   for( var g=0; g<numCerts; ++g )

   {

      var ue = oGroups[0].userEntities[g];

      var oCert = ue.defaultEncryptCert;

      if( oCert == null )

         oCert = ue.certificates[0];

      cMsg += oCert.subjectCN + ", " + ue.email + "\n";

      var oRDN = oCert.subjectDN;

      if( ue.email )

      {

         mailList[g] = ue.email;

      }

      else

         if ( oRDN.e )

         {

            mailList[g] = oRDN.e;

         }

   }

   var result = app.alert( cMsg );

Example 3

List all the entries in an array of groups.

   var  groups = security.chooseRecipientsDialog( oOptions );

   for( g in groups ) {

      console.println( "Group No. " + g );

      // Permissions

      var perms = groups[g].permissions;

      console.println( "Permissions:" );

      for(p in perms) console.println( p + " = " + eval("perms." +p));

      // User Entities

      for( u in groups[i].userEntities ) {

      var user = groups[g].userEntities[u];

      console.println( "User No. " + u );

      for(i in user) console.println( i + " = " + eval("user." +i));

      }

   }

chooseSecurityPolicy

Displays a dialog box to allow a user to choose from a list of security policies, filtered according to the options.

Note:Can be executed only during a batch, console, or application initialization event. See Privileged versus non-privileged context for details. This method will display UI.

Parameters

Returns

Returns a single SecurityPolicy object or null if the user cancelled the selection.

Example

Choose a policy and display the name.

   var options = { cHandler: security.APSHandler };

   var policy = security.chooseSecurityPolicy( options );

   console.println("The policy chosen was: " + policy.name);

security.APSHandler is one of the security constants.

exportToFile

Exports a Certificate object to a local disk as a raw certificate file.

Note:Data being written must be data for a valid certificate; arbitrary data types cannot be written. This method will not overwrite an existing file.

See also security.importFromFile.

Parameters

Returns

The path of the file that was written, if successful.

Example

   var outPath = security.exportToFile(oCert, "/c/outCert.cer");

getHandler

Obtains a SecurityHandler object. The caller can create as many new engines as desired and each call to getHandler creates a new engine. However, there is only one UI engine.

Note:This method is available from batch, console, and app initialization events. See Privileged versus non-privileged context for details.

Backward Compatibility: Because Adobe.PPKMS is no longer available as a separate handler starting with Acrobat 7.0, invoking getHandler with cName as “Adobe.PPKMS” returns the engine associated with Adobe.PPKLite handler.

Parameters

Returns

The SecurityHandler object specified by cName. If the handler is not present, returns a null object.

Example

Select the Adobe.PPKLite SecurityHandler.

   // Validate signatures on open

   security.validateSignaturesOnOpen = true;

   

   // List all available signature handlers

   var a = security.handlers;

   for (var i = 0; i < a.length; i++)

      console.println("a["+i+"] = "+a[i]);

   

   // Use "Adobe.PPKLite" handler engine for the UI

   var ppklite = security.getHandler(

      security.PPKLiteHandler, true);

   // Log in

   ppklite.login("dps017", "/C/profiles/DPSmith.pfx");

See also the example following signatureSign for a continuation of this example.

getSecurityPolicies

Returns the list of security policies currently available, filtered according to the options specified. The master list of security policies will be updated prior to filtering. The default SecurityHandler objects are used to retrieve the latest policies. If no policies are available or none meet the filtering restrictions, null will be returned.

Note:You may be able to retrieve more policies by calling login on the default SecurityHandler objects before calling this function.

Can be executed only during a console or application initialization event. Not available in Adobe Reader.

Parameters

Returns

An array of SecurityPolicyOptions objects or null.

SecurityPolicyOptions object

The SecurityPolicyOptions object has the following properties:

Example 1

Retrieve the list of favorite PPKLite policies and display the names. This example uses security.PPKLiteHandler (see security constants).

   var options = { bFavorites:true, cHandler:security.PPKLiteHandler };

   var policyArray = security.getSecurityPolicies( { oOptions: options } );

   for( var i = 0; i < policyArray.length; i++)

      console.println( policyArray[i].name );

Example 2

Force the login, retrieve the list of APS policies, and display the names. This example uses security.APSHandler (see security constants).

   var aps = security.getHandler( security.APSHandler, true );

   aps.login();

   var options = { cHandler: security.APSHandler };

   var policyArray = security.getSecurityPolicies({

      bUI: true,

      oOptions: options });

   for(var i = 0; i < policyArray.length; i++)

      console.println( policyArray[i].name );

importFromFile

Reads a raw data file and returns the data as an object with a type specified by cType. The file being imported must be a valid certificate. See also security.exportToFile

Parameters

Returns

A Certificate object.

Example

   var oMyCert = security.importFromFile("Certificate", "/c/myCert.cer");

 

importSettings

Allows limited functionality similar to Preferences > Security panel > Security Settings > Import, but it imports settings from an embedded file. This allows you to import digital IDs from an attached acrobat security settings file triggered by a button click from the containing document. Only digital IDs can be imported using this method, and other security settings, including trust settings, cannot be modified using this method. This method can only be triggered from a console, batch, or field mouse up event.

To create a file that can be embedded for this script, export the settings using Preferences > Security panel > Security Settings > Export. In the example below, if the script is attached to a button click event and the document represented by this is correctly formed, when the button is clicked it will bring up a simple import dialog for digital IDs.

Note:Security settings files must be certified in order to be considered valid.

Parameters

Returns

The number of digital IDs installed, or -1 if cancelled.

Example

   security.importSettings(this, "ids.acrobatsecuritysettings", true);