Custom Certificate Preferences

The cCustomCertPrefs directory provides the means to use certificate-specific settings to modify application behavior when it encounters a particular certificate. As the application builds a certificate chain, it compares the information it finds in the certificate with that in the registry to see if there is a match. If there is a match, the custom settings are used to override the application’s default behavior. Certificates that chain up to a CA that match those configured here or that contain recognized extensions will use the preferences set in this directory.

You can use any of the preferences available in cASPKI in your customized preference under \cASPKI\cASPKI\cCustomCertPrefs. Custom certificate preferences are specified differently than when they are used globally under \ASPKI. For example, The naming and path convention is always c<key>:c<index>:<type>Value, where the global preference would be sSignCertOID and the custom preference would be cSignCertOID (the data type is associated with the Value subkey rather than the key.

Certificates are identified by creating a hash of a unique identifier and appending it to c such as c312E322E3834302E3131343032312E310000. When the application finds in a certificate chain a hash that matches the hash in the registry, the custom preference is used. Locate custom preferences under one of the following methods:

  • Base 16 encoded SHA1 public key hash of the CA certificate. A SHA1 hash of the public key is used instead of SHA1 hash of the certificate so that the preferences can survive cross certification where the SHA1 hash of the public key remains the same.

  • Hex representation of an OID followed by two NULL characters.

Identifying Certificates

Identify certificates by using a hash of their public key. Adobe’s Certificate Viewer provides an easy way to get the public key hash. To do so:

  1. Import the certificate into Acrobat.

  2. Open the Trusted Identify Manager.

  3. Choose Certificates from the Display drop-down list.

  4. Highlight the certificate you will use (an ICA).

  5. Choose Show Certificate.

  6. Choose the Details tab.

_images/certificate_viewer_details.gif

  1. Highlight the SHA1 digest of the public key.

  2. Copy the hash in the lower panel to the clipboard. This example uses 5D800FA2F49D4816FCA014B B9442665922BA8A77.

  3. Open the registry

  4. Navigate to HKEY_CURRENT_USER\Software\Adobe\(product name)\(version)\Security\cASPKI\cASPKI\cCustomCertPrefs\.

  5. Right-click on cCustomCertPrefs.

  6. Choose New > Key.

  7. Enter “c” followed by the public key hash you just created. For example: c5D800FA2F49D4816 FCA014BB9442665922BA8A77.

This registry key is now ready to be populated with custom preferences.

_images/reg_customcertpref.gif

Creating an addressbook.acrodata file

If you want to pre-configure the installer to trust a custom certificate or leverage trusted root CAs or certificates in digital signature workflows, you can export the required certificate to an addressbook.acrodata file. That file can then be embedded in the installer with the Customization Wizard or deployed by other means post-install.

To do so:

  1. Open Acrobat.

  2. Go to Preferences:

  • In the classic UI: Edit > Preferences.

  • In the modern UI: Hamburger menu > Preferences.

  1. Choose Signatures > Identities & Trusted Certificates > More > Trusted Certificates.

  2. Choose Import.

  3. Browse to the certificate you want to trust. This is usually located at C:\Users\<username>\AppData\Roaming\Adobe\Acrobat\<track name>\Security.

  4. Choose Open.

    1. Choose Import and complete the workflow.

Adding Certificate Preferences

On a Windows machine, certificate-specific preferences can be added by following the steps below:

  1. Navigate to HKEY_CURRENT_USER\Software\Adobe\(product name)\(version)\Security\cASPKI\cASPKI\cCustomCertPrefs\<your ID hash>.

  2. Add the needed containers and keys. Custom entries under cCustomCertPrefs are always a cab and the name is prepended with a “c.” For example, to set a timestamp server provider preference, you would use the available timestamp preferences. While the key list shows sPassword as a valid name, when it is used under CustomCertPrefs, the entry should be renamed to cPassword.

Requirements will vary based on your specific need:

  • cAdobe_LTVProvider

  • cAdobe_TSPProvider

  • cAdobe_OCSPRevChecker

  • cAdobe_CRLRevChecker

  • cAdobe_ChainBuilder

Setting chain scope

You can associate a custom certificate with a chain scope. iStart and iEnd can be used to specify for what parts of a certificate chain a custom certificate preference will apply. They are always used at the container level of c0, c1, c2, and so on. For example, Acrobat could be configured to search for acceptable policy OIDS only in the certificates that are the first, second, and third levels below the root CA.

_images/certchain.png _images/reg_iStart.gif
Scoping certificate

Name

Type

Description

iStart

int

(v 7.0) Determines the start of the preference relevance depth relative to the certificate chain. By default, the preference starts at the current level.

iEnd

int

(v 7.0) Determines the end of the preference relevance depth relative to the certificate chain. By default the depth of the preference is MaxUns32

To specify a scope within a chain:

  1. Navigate to <root>\cCustomCertPrefs\<certificate public key hash>\cAdobe_ChainBuilder\cAcceptablePolicyOIDs\c0.

  2. Highlight c0, right-click, and choose New > DWORD.

  3. Enter the field names iStart and iEnd.

  4. Right-click on a field and choose Modify.

  5. Set the Value Data field to specify the needed start or end range.

  6. Choose OK.

  7. Restart the application.

_images/reg_iStart2.gif

Example: Identrus Compliance

Acrobat has two custom certificate preferences that enable Identrus compliance at HKCU\Software\Adobe\Adobe Acrobat\Security\cASPKI\cASPKI\cCustomCertPrefs\<hash of Identrus OID>. You can use this as a template for a similar custom certificate preference:

  • c312E322E3834302E3131343032312E310000

  • c312E322E3834302E3131343032312E312E312E310000

Whenever a credential that chains up to an Identrus CA is used for signing or signature validation, the application follows the Identrus rule set rather than the default rule set. The custom certificate preferences enable Acrobat to recognize Identrus certificates and process them as required by Identrus.

When Acrobat starts for the first time, it checks whether bCustomPrefsCreated is set. If not set to true, Acrobat writes out the Identrus rule set that is hard coded within Acrobat. If it’s already set, then writing out the Identrus rules is skipped.

If the Identrus rules in Acrobat require an update without updating Acrobat, then create a custom installer (tuned with the Wizard) that sets bCustomPrefsCreated ``to ``true and writes out the new Identrus rules. Acrobat will then first check whether custom preferences have been created. If they are already created, then Acrobat won’t write out the Identrus rules within Acrobat, and those written out by the custom installer will be respected by ASPKI.

An Identrus CA is identified by the certificate policy OID 1.2.840.114021.1.1.1 present in the production Identrus root CA. However, the certificate policy OID present in their test root CA is different, and to be able to test Acrobat against the test Identrus environments, Acrobat also uses the same Identrus rules for CAs that have the certificate policy OID 1.2.840.114021.1. Identrus certificates must contain one of the OIDs supported by the AcceptablePolicyOIDs preference. If the OID is not present, the certificate is deemed to be invalid and the signature will also be invalid.

Keyname Summary
{keyname} {summary}