Security and Signature APIs

data-id=79993

data-id=security

data-id=id925

security

The security object is a static JavaScript object that exposes security-related PDF functions such as encryption and digital signatures. Security functions are performed using a SecurityHandler object, which is obtained from the security object using the getHandler method.

Note

The security object is available without restriction, including in Adobe Reader. The methods and properties of the security object can only be executed during batch, console or application initialization events including in Adobe Reader, except where otherwise stated. See also priv. The event object contains a discussion of JavaScript events.

data-id=66342

data-id=security-constants

data-id=id926

security constants

Beginning with Acrobat 7.0, several convenience strings are defined within the security object. The constants are held as properties of the wrapper objects listed below.

data-id=75621

HandlerName object

These are constants used when determining which handler to use.

Example: The constant (string) security.StandardHandler is used to specify the handler property of the SecurityPolicy object.

security.getHandler(security.PPKLiteHandler, true);

data-id=60135

EncryptTarget Object

These constants are used when determining what data a policy is encrypting. They can be used in the target property of the SecurityPolicy object.

Example:

var filterOptions = { target: security.EncryptTargetAttachments };
security.chooseSecurityPolicy( { oOptions: filterOptions } );

data-id=security-properties

data-id=id927

security properties

data-id=27159

data-id=handlers

data-id=id928

handlers

An array containing the language-independent names of the available security handlers that can be used for encryption or signatures.

See also getSecurityPolicies.

The following information applies to different versions of Acrobat:

• Beginning with Acrobat 6.0, access to this property is unrestricted, to allow querying to see which handlers are available.
• In Acrobat 6.0, this call returned three handlers, Adobe.PPKLite, Adobe.PPKMS, and Adobe.AAB. Starting with Acrobat 7.0, all the functionality provided by Adobe.PPKMS has been rolled into Adobe.PPKLite, and Adobe.PPKMS is no longer available as a separate handler.
• Beginning with Acrobat 7.0, a new handler is available, Adobe.APS. This handler is used for authentication prior to calling any of the methods encryptUsingPolicy, getSecurityPolicies, or chooseSecurityPolicy. It has no other valid usage currently.
• Beginning with Acrobat 7.0, security constants are defined for each of the handlers. (Adobe.AAB is an exception. No constant was added because this handler will probably be deprecated in the near future.) These constants should be used when creating a new handler instance with getHandler or comparing against the handlers list.

Example: Get the list of security handlers available on this system:

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

     console.println(security.handlers[i])

The output to the console might be

Adobe.APS
Adobe.PPKLite
Adobe.PPKMS
Adobe.AAB

data-id=78307

data-id=validatesignaturesonopen

data-id=id929

validateSignaturesOnOpen

Gets or sets the user-level preference that causes signatures to be automatically validated when a document is opened.

Note

The property can be used to get in all situations, but can only set new values during a batch, console, or application initialization event. See priv.

data-id=security-methods

data-id=id930

security methods

data-id=42796

data-id=chooserecipientsdialog

data-id=id931

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 priv.

Parameters

Returns

An array of Group objects.

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

data-id=67259

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

data-id=20074

data-id=choosesecuritypolicy

data-id=id932

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 priv. 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.

data-id=82432

data-id=exporttofile

data-id=id933

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

data-id=71913

data-id=gethandler

data-id=id934

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 priv.

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.

data-id=45284

data-id=getsecuritypolicies

data-id=id935

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.

data-id=95227

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

data-id=36368

data-id=importfromfile

data-id=id936

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

data-id=14320

data-id=importsettings

data-id=id937

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

data-id=25690

data-id=securityhandler

data-id=id938

SecurityHandler

SecurityHandler objects are used to access security handler capabilities such as signatures, encryption, and directories. Different security handlers have different properties and methods. This section documents the full set of properties and methods that security objects may have. Individual SecurityHandler objects may or may not implement these properties and methods.

SecurityHandler objects can be obtained using the security.getHandler method.

The JavaScript interface for Adobe.PPKLite signatures was introduced in Acrobat 5.0, and the remainder of the JavaScript interface was introduced in Acrobat 6.0. Prior to Acrobat 6.0, there was no support in Acrobat to enable JavaScript in third-party security handlers.

Not all security handlers are JavaScript-enabled. Not all JavaScript enabled handlers are enabled for all security operations. Third-party public key security handlers may support JavaScript, but only if they use the new PubSec programming interface that was introduced in Acrobat 6.0.

JavaScript-enabled handlers provided by Adobe include:

• The Adobe.PPKLite security handler supports signatures and encryption. On the Windows operating system, it provides directory access through the Microsoft Active Directory Scripting Interface (ADSI).
• The Adobe.AAB security handler provides a local address book and support for directory operations.

Note

The Standard security handler, used for password encryption of documents, is not JavaScript-enabled in general. However, starting with Acrobat 7.0, encryption using Standard security is possible using predefined policies. See encryptUsingPolicy for more details.

Also starting with Acrobat 7.0, the Adobe.APS handler can be used for encryption with the encryptUsingPolicy method. This handler also makes a directory available through the directory services, but because no certificates are returned from this directory, it is of limited general use.

Note

SecurityHandler objects can only be created using the Security object getHandler method. This method is available only for batch, console, and application initialization events (see priv for details) and is available in Adobe Reader.

data-id=securityhandler-properties

data-id=id939

SecurityHandler properties

data-id=84619

data-id=appearances

data-id=id940

appearances

An array containing the language-dependent names of the available user-configured appearances for the specified security handler. Appearances are used to create the on-page visual representation of a signature when signing a signature field. The name of an appearance can be specified as a signature info object property when signing a signature field using the Field object signatureSign method.

Acrobat provides a standard signature appearance module that is used by Adobe signature plug-ins and that can also be used by third-party signature plug-ins. This standard signature appearance module is preconfigured with one appearance and can be configured by users to contain more appearances. The name of the one pre-configured appearance, called Standard Text in the user interface, is not returned by this property.

If a security handler does not support selection of appearances, this property will return null.

data-id=69297

data-id=digitalids

data-id=id941

digitalIDs

The certificates that are associated with the currently selected digital IDs for this security handler.

The return value is a generic object with the following properties:

The Adobe.PPKLite security handler returns all currently available digital IDs present in Password-protected digital ID files (both PKCS#12 and APF) and, on Windows, IDs present in the Windows (MSCAPI) store.

Both oEndUserSignCert and oEndUserCryptCert properties can be set using the user-interface. oEndUserSignCert can also be set using the login method. This means that oEndUserCryptCert will only be returned when using a Security Handler object that is obtained using the getHandler method with bUIEngine set to true.

Example: Export to a file the certificate that is associated with the currently selected digital IDs.

var sh = security.getHandler( "Adobe.PPKMS", true );
var ids = sh.digitalIDs;
var oCert = ids.oEndUserSignCert;
security.exportToFile( oCert, "/c/MySigningCert.cer" );

data-id=57042

data-id=directories

data-id=id942

directories

An array of the available Directory objects for this Security Handler. New Directory objects can be created using the newDirectory method.

data-id=53498

data-id=directoryhandlers

data-id=id943

directoryHandlers

An array containing the language-independent names of the available directory handlers for the specified security handler. For example, the Adobe.PPKMS security handler has a directory handler named Adobe.PPKMS.ADSI that supports queries using the Microsoft Active Directory Script Interface (ADSI). Valid directory handler names are required when activating a new Directory object using its info property.

data-id=33360

data-id=docdecrypt

data-id=id944

docDecrypt

Returns true, if the security handler is capable of decrypting PDF files.

data-id=32731

data-id=docencrypt

data-id=id945

docEncrypt

Returns true, if the security handler is capable of encrypting PDF files.

data-id=99723

data-id=isloggedin

data-id=id946

isLoggedIn

Returns true if currently logged into this SecurityHandler object. See the login method.

Different security handlers will have their own rules for determining the value of this property. The Adobe.PPKLite handler will return true if a user is logged in to a profile file (also called credential file, implemented as a PKCS#12 file). Adobe.PPKMS will always return true.

Example: Generic script to illustrate isLoggedIn.

var ppklite = security.getHandler("Adobe.PPKLite", true);
console.println( "Is logged in = " + ppklite.isLoggedIn ); // False
ppklite.login( "dps017", "/C/signatures/DPSmith.pfx");
console.println( "Is logged in = " + ppklite.isLoggedIn ); // True

data-id=43875

data-id=id947

data-id=id948

loginName

The name associated with the actively selected signing digital ID for the security handler. This may require that the login method be called to select a signing credential. The return value is null if a signing credential is not selected or if the security handler does not support this property.

data-id=63004

data-id=loginpath

data-id=id949

loginPath

The device-independent path to the user’s profile file used to log in to the security handler. The return value is null if no one is logged in, if the security handler does not support this property, or if this property is irrelevant for the currently logged in user.

data-id=51304

data-id=id950

data-id=id951

name

The language-independent name of the security handler. Example values for the Default Certificate, Windows Certificate, and Entrust Security Handlers are Adobe.PPKLite, Adobe.PPKMS, and Entrust.PPKEF. All security handlers must support this property.

data-id=42384

data-id=signauthor

data-id=id952

signAuthor

Specifies whether the security handler is capable of generating certified documents. A certified document is signed with both a byte-range signature and an object signature. Object signatures, which are generated by traversing the document’s object tree, are used to detect and prevent modifications to a document. See the mdp property of the SignatureInfo object for details regarding modification detection and prevention (MDP) settings.

data-id=67664

data-id=signfdf

data-id=id953

signFDF

Indicates that the security handler is capable of signing FDF files.

data-id=18752

data-id=signinvisible

data-id=id954

signInvisible

Specifies whether the security handler is capable of generating invisible signatures.

data-id=44220

data-id=signvalidate

data-id=id955

signValidate

Indicates whether the security handler is capable of validating signatures.

data-id=31575

data-id=signvisible

data-id=id956

signVisible

Specifies whether the security handler is capable of generating visible signatures.

data-id=13603

data-id=id957

data-id=id958

uiName

The language-dependent string for the security handler. This string is suitable for user interfaces. All security handlers must support this property.

data-id=51812

data-id=validatefdf

data-id=id959

validateFDF

Returns true, if the security handler is capable of validating signatures over FDF files.

data-id=securityhandler-methods

data-id=id960

SecurityHandler methods

data-id=75651

data-id=login

data-id=id961

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 true if the login succeeded, false otherwise.

data-id=81900

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.

data-id=95399

data-id=logout

data-id=id962

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.

data-id=36849

data-id=newdirectory

data-id=id963

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

data-id=96919

data-id=newuser

data-id=id964

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

data-id=11628

data-id=setpasswordtimeout

data-id=id965

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

data-id=30747

data-id=securitypolicy

data-id=id966

SecurityPolicy

The Security Policy object represents a group of security settings used to apply encryption to a document. It is acquired as the return value of both getSecurityPolicies and chooseSecurityPolicy.

data-id=77960

data-id=securitypolicy-properties

data-id=id967

SecurityPolicy properties

data-id=51916

data-id=id968

data-id=id969

SignatureInfo

A generic JavaScript object that contains the properties of a digital signature. Some properties are supported by all handlers, and additional properties can be supported.

The SignatureInfo object is returned by the Field object methods signatureValidate and signatureInfo and is passed to the FDF object methods signatureSign and signatureValidate.

Writable properties can be specified when signing the object.

data-id=signatureinfo-properties

data-id=id970

SignatureInfo properties

All handlers define the following properties.

data-id=40445

data-id=signatureinfo-object-public-key-security-handler-properties

data-id=id972

SignatureInfo object public key security handler properties

Public key security handlers may define the following additional properties:

data-id=71840

data-id=status-and-idvalidity-properties

data-id=id973

status and idValidity properties

The following table list the codes returned by the SignatureInfo Object, status and idValidity properties.

data-id=40865

data-id=validity-values

data-id=id974

Validity Values

The following codes are returned by the docValidity and objValidity properties. (See SignatureInfo object public key security handler properties). They provide a finer granularity of the validity of the signature than the status property.

data-id=13196

data-id=private-validity-values

data-id=id975

Private Validity Values

Verification of the validity of the signer’s identity is specific to the handler that is being used to validate the identity. This value may contain useful information regarding an identity. The identity is returned in the idPrivValidity property. Values for Adobe.PPKMS and Adobe.PPKLite security handlers are shown here. This value is also mapped to an idValidity value that is common across all handlers.

data-id=64083

data-id=modification-detection-and-prevention-mdp-values

data-id=id976

Modification Detection and Prevention (MDP) Values

Modification detection and prevention (MDP) settings control which changes are allowed to occur in a document before the signature becomes invalid. Changes are recorded outside of the byte range, for signature fields, and can include changes that have been incrementally saved as part of the document or changes that have occurred in memory between the time that a document is opened and when the signature is validated. MDP settings may only be applied to the first signature in a document. Use of MDP will result in an certification signature. MDP has one of the following four values:

• allowAll: Allow all changes to a document without any of these changes invalidating the signature. This results in MDP not being used for the signature. This was the behavior for Acrobat 4.0 through 5.1.
• allowNone: Do not allow any changes to the document without invalidating the signature. Note that this will also lock down the author’s signature.
• default: Allow form field fill-in if form fields are present in the document. Otherwise, do not allow any changes to the document without invalidating the signature.
• defaultAndComments: Allow form field fill-in if form fields are present in the document and allow annotations (comments) to be added, deleted or modified. Otherwise, do not allow any changes to the document without invalidating the signature. Note that annotations can be used to obscure portions of a document and thereby affect the visual presentation of the document.