SecurityHandler methods

login

logout

newDirectory

newUser

setPasswordTimeout

login

Provides a mechanism by which digital IDs can be accessed and selected for a particular Security Handler. Through the user interface, a default digital ID can be selected that persists either eternally or for as long as the application is running. If such a selection has been made through the UI, it might not be necessary to log into a Security Handler prior to using the digital ID.

Parameters tend to be specific to a particular handler. The behavior for Adobe.PPKLite and Adobe.PPKMS handlers is specified below.

The parameters cPassword and cDIPath are provided for backward compatibility, or they can be included as properties of the oParams object. This latter method is the preferred calling convention beginning in Acrobat 6.0.

See also logout, newUser, and loginName.

Parameters

Returns

Returns true if the login succeeded, false otherwise.

LoginParameters Object

This generic JavaScript object contains parameters for the login method. It has the following properties:

Example 1

Log in and log out.

   // Use the "Adobe.PPKLite" security handler object for the UI

   var ppklite = security.getHandler( security.PPKLiteHandler, true );

   var oParams = { cPassword: "dps017", cDIPath: "/C/DPSmith.pfx" }

   ppklite.login( oParams );

   <..... make a signature field and sign it ......>

   ppklite.logout();

Use UI to select a credential, when already logged in.

   ppklite.login(

   { oParams:

      { oEndUserSignCert: {},
      cMsg: "Select your Digital ID" },

      bUI : true

   } );

Log in and select the signing credentials

   var oCert = { SHA1Hash: "00000000" };

   ppklite.login(

   { oParams:

      { cDIPath: "/C/test/DPSmith.pfx",
         cPassword: "dps017",

         oEndUserSignCert: oCert,

         cMsg: "Select your Digital ID"

      },
   bUI : true

   });

Example 2

Use the "Adobe.PPKMS" security handler object, and select the credentials to use when signing.

   var ppkms = security.getHandler( "Adobe.PPKMS" );

   var oCert = myCerts[0];

   ppkms.login( { oParams: { oEndUserSignCert: oCert } } );

Example 3

Use security.APSHandler, see security constants.

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

   var oParams = { cUserName: "Acrobat", cPassword: "adobedon" };

   aps.login( oParams );

   <..... encrypt a document using this handle and a policy id .....>

   aps.logout();

See signatureSign for details on signing a PDF document.

logout

Logs out for the SecurityHandler object. This method is used by Adobe.PPKLite, not by Adobe.PPKMS.

Also see the login method.

Returns

Beginning in Acrobat 6.0, returns true if the logout succeeded, false otherwise. Previous Acrobat releases did not generate a return value.

newDirectory

Returns a new Directory object. This object must be activated using its info property before it is marked for persistence and before it can be used for searches. Existing directory objects can be discovered using the directories property.

Returns

A new Directory object

newUser

Supports enrollment with Adobe.PPKLite and Adobe.PPKMS security handlers by creating a new self-sign credential.

Note:This method will not allow the user to overwrite an existing file.

Parameters

Returns

true if successful, throws an exception if not successful.

Example 1

Create a new PPKLite self-sign credential (Acrobat 5.0 syntax)

   var ppklite = security.getHandler(security.PPKLiteHandler);

   var oRDN = { cn: "Fred NewUser", c: "US" };

   var oCPS = {oid: "1.2.3.4.5",

      url: "http://www.example.com/mycps.html",

      notice: "This is a self generated certificate, hence the "

         + "recipient must verify it’s authenticity through an out "

         + "of band mechanism" };

   ppklite.newUser( "testtest", "/d/temp/FredNewUser.pfx", oRDN, oCPS);

   

   // Alternate generic object syntax, allowing additional parameters

   var oParams = {

      cPassword : "myPassword",

      cDIPath : "/d/temp/FredNewUser.pfx",

      oRDN : oRDN,

      oCPS : oCPS,

      bUI : false

   };

   ppklite.newUser( oParams );

Example 2

Use a certificate from an existing signed field to create the RDN

   var f = this.getField( "mySignature" );

   f.signatureValidate();

   var sigInfo = f.signatureInfo();

   var certs = sigInfo.certificates;

   var oSubjectDN = certs[0].subjectDN;

   

   ppklite.newUser({

      cPassword: "dps017",

      cDIPath: "/c/temp/DPSmith.pfx",  

      oRDN: oSubjectDN

   });

setPasswordTimeout

Sets the number of seconds after which password should expire between signatures. This method is only supported by the Adobe.PPKLite security handler. For this handler the default timeout value for a new user is 0 (password always required).

Parameters

Returns

Throws an exception if the user has not logged in to the Adobe.PPKLite security handler, or unsuccessful for any other reason.

Example

This example logs in to the PPKLite security handler and sets the password timeout to 30 seconds. If the password timeout has expired—30 seconds in this example—the signer must provide a password. The password is not necessary if the password has not timed out.

   var ppklite= security.getHandler( "Adobe.PPKLite" );

   ppklite.login( "dps017", "/d/profiles/DPSmith.pfx" );
   ppklite.setPasswordTimeout( "dps017", 30 );