8.2. Setting up Publishing

The general process to configure publishing involves setting up a publisher to publish the certificates or CRLs to the specific location. There can be a single publisher or multiple publishers, depending on how many locations will be used. The locations can be split by certificates and CRLs or finer definitions, such as certificate type. Rules determine which type to publish and to what location by being associated with the publisher.
  1. Publishing to file simply publishes the CRLs or certificates to text files on a given host. This is covered in Section 8.2.1, “Configuring Publishing to a File”.
  2. Publishing to an OCSP Manager is a way to publish CRLs to a specific location for client verification. This is covered in Section 8.2.2, “Configuring Publishing to an OCSP”.
    For OCSP publishing, CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
  3. LDAP publishing publishes the certificates to specific entries within an LDAP database, so other clients can access the entries. There are three steps for configuring LDAP publishing:
    1. Configure the Directory Server to which certificates will be published. Refer to Section 8.2.3.1, “Configuring the LDAP Directory”.
    2. Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but, generally, LDAP publishers do not need changed. For more information, see Section 8.2.3, “Configuring Publishing to an LDAP Directory”.
    3. Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
      For details about setting up mappers, see Section 8.2.3.3, “Creating Mappers”.
After setting up the publishing locations, then define rules to determine what certificates are published where (Section 8.2.4, “Creating Rules”). Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. The same certificate can be published to a file and to an LDAP directory by matching a file-based rule and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. There can be different rules for different kinds of certificates or different kinds of CRLs. The rule first determines if the object meets the criteria by matching the type and predicate set in the rule. The destination of matching objects is determined by the publisher and mapper associated with the rule.
After setting up all of the publishers, mappers, and rules, enable publishing (Section 8.2.5, “Enabling Publishing”). As soon as publishing is enabled, the server starts publishing immediately. If the publishers, mappers, and rules are not completely configured, publishing may not work correctly or at all.

8.2.1. Configuring Publishing to a File

Publishers must be created and configured for each publishing location; publishers are not automatically created for publishing to a file. To publish all files to a single location, create one publisher. To publish to different locations, create a publisher for each location. A location can either contain an object type, like user certificates, or a subset of an object type, like West Coast user certificates.
To create publishers for publishing to files:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
    The Publishers Management tab, which lists configured publisher instances, opens on the right.
    Using the Publishers Management Tab to Create Publishers

    Figure 8.1. Using the Publishers Management Tab to Create Publishers


  3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
    Select Publisher Plug-in Implementation Window

    Figure 8.2. Select Publisher Plug-in Implementation Window


  4. Select the FileBasedPublisher module, then open the editor window.
    This is the module that enables the Certificate Manager to publish certificates and CRLs to files.
  5. Configure the information for publishing the certificate:
    • The publisher ID, an alphanumeric string with no spaces like PublishCertsToFile
    • The path to the directory in which the Certificate Manager should publish the files. The path can be an absolute path or can be relative to the Certificate System instance directory. For example, /export/CS/certificates.
    • The file type to publish, by selecting the checkboxes for DER-encoded files, base-64 encoded files, or both.
    • The format of the timestamp to use to name the published certificate or CRL files.
    • For CRLs, whether to generate a link in the file to go to the latest CRL. If enabled, the link assumes that the name of the CRL issuing point to use with the extension will be supplied in the crlLinkExt field.
    • For CRLs, whether to compress (zip) CRLs and the compression level to use.
After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.2. Configuring Publishing to an OCSP

A publisher must be created and configured for each publishing location; publishers are not automatically created for publishing to the OCSP responder. Create a single publisher to publish everything to s single location, or create a publisher for every location to which CRLs will be published. Each location can contain a different kind of CRL.
To create publishers for publishing CRLs to an OCSP:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Publishers.
    Publishers Management Tab

    Figure 8.3. Publishers Management Tab


  3. Click Add to open the Select Publisher Plug-in Implementation window, which lists registered publisher modules.
    Select Publisher Plug-in Implementation Window

    Figure 8.4. Select Publisher Plug-in Implementation Window


  4. Select the OCSPPublisher module, then open the editor window. This is the publisher module that enables the Certificate Manager to publish CRLs to the Online Certificate Status Manager.
    Publisher Editor Window

    Figure 8.5. Publisher Editor Window


    The host can be the fully-qualified domain name or an IPv4 or IPv6 address.
  5. Set the publisher ID, an alphanumeric string with no spaces like PublishCertsToOCSP; the fully-qualified domain name, such as ocspResponder.example.com, and port number of the Online Certificate Status Manager; and the default path, /ocsp/ee/ocsp/addCRL.
After configuring the publisher, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.3. Configuring Publishing to an LDAP Directory

Configuring LDAP publishing is similar to other publishing procedures, with additional steps to configure the directory:
  1. Configure the Directory Server to which certificates will be published. Certain attributes have to be added to entries and bind identities and authentication methods have to be configured.
  2. Configure a publisher for each type of object published: CA certificates, cross-pair certificates, CRLs, and user certificates. The publisher declares in which attribute to store the object. The attributes set by default are the X.500 standard attributes for storing each object type. This attribute can be changed in the publisher, but, generally, it's not necessary to change the LDAP publishers.
  3. Set up mappers to enable an entry's DN to be derived from the certificate's subject name. This generally does not need set for CA certificates, CRLs, and user certificates. There can be more than one mapper set for a type of certificate. This can be useful, for example, to publish certificates for two sets of users from different divisions of a company who are located in different parts of the directory tree. A mapper is created for each of the groups to specify a different branch of the tree.
    For details about setting up mappers, see Section 8.2.3.3, “Creating Mappers”.
  4. Create rules to connect publishers to mappers, as described in Section 8.2.4, “Creating Rules”.

8.2.3.1. Configuring the LDAP Directory

Before certificates and CRLs can be published, the Directory Server must be configured to work with the publishing system.
  1. Set up the entry for the CA. For the Certificate Manager to publish its CA certificate and CRL, the directory must include an entry for the CA.
    The Certificate Manager automatically creates an entry for the CA in the directory. This option is set in both the CA and CRL mapper instances and enabled by default. If the directory restricts the Certificate Manager from creating entries in the directory, turn off this option in those mapper instances, and add an entry for the CA manually in the directory.
    When adding the CA's entry to the directory, select the entry type based on the DN of the CA:
    • If the CA's DN begins with the cn component, create a new person entry for the CA. Selecting a different type of entry may not allow the cn component to be specified.
    • If the CA's DN begins with the ou component, create a new organizationalunit entry for the CA.
    The entry does not have to be in the certificationAuthority object class. The Certificate Manager will convert this entry to the certificationAuthority object class automatically by publishing its CA's signing certificate.
    For more information on creating directory entries, see the Red Hat Directory Server documentation.
  2. Add the correct schema elements to the CA and user directory entries.
    For a Certificate Manager to publish certificates and CRLs to a directory, it must figured with specific attributes and object classes.
    Certificate Type Schema Reason
    End-entity userCertificate;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the certificate.
    This is a multi-valued attribute, and each value is a DER-encoded binary X.509 certificate. The LDAP object class named inetOrgPerson allows this attribute. The strongAuthenticationUser object class allows this attribute and can be combined with any other object class to allow certificates to be published to directory entries with other object classes. The Certificate Manager does not automatically add this object class to the schema table of the corresponding Directory Server.
    If the directory object that it finds does not allow the userCertificate;binary attribute, adding or removing the certificate fails.
    CA caCertificate;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the certificate.
    The Certificate Manager publishes its own CA certificate to its own LDAP directory entry when the server starts. The entry corresponds to the Certificate Manager's issuer name.
    This is a required attribute of the certificationAuthority object class. The Certificate Manager adds this object class to the directory entry for the CA if it can find the CA's directory entry.
    CRL certificateRevocationList;binary (attribute)
    This is the attribute to which the Certificate Manager publishes the CRL.
    The Certificate Manager publishes the CRL to its own LDAP directory entry. The entry corresponds to the Certificate Manager's issuer name.
    This is an attribute of the certificationAuthority object class. The value of the attribute is the DER-encoded binary X.509 CRL. The CA's entry must already contain the certificationAuthority object class for the CRL to be published to the entry.
  3. Set up a bind DN for the Certificate Manager to use to access the Directory Server.
    The Certificate Manager user must have read-write permissions to the directory to publish certificates and CRLs to the directory so that the Certificate Manager can modify the user entries with certificate-related information and the CA entry with CA's certificate and CRL related information.
    The bind DN entry can be either of the following:
    • An existing DN that has write access, such as the Directory Manager.
    • A new user which is granted write access. The entry can be identified by the Certificate Manager's DN, such as cn=testCA, ou=Research Dept, o=Example Corporation, st=California, c=US.

      NOTE

      Carefully consider what privileges are given to this user. This user can be restricted in what it can write to the directory by creating ACLs for the account. For instructions on giving write access to the Certificate Manager's entry, see the Directory Server documentation.
  4. Set the directory authentication method for how the Certificate Manager authenticates to Directory Server. There are three options: basic authentication (simple username and password); SSL without client authentication (simple username and password); and SSL with client authentication (certificate-based).
    See the Red Hat Directory Server documentation for instructions on setting up these methods of communication with the server.

8.2.3.2. Configuring LDAP Publishers

The Certificate Manager creates, configures, and enables a set of publishers that are associated with LDAP publishing. The default publishers (for CA certificates, user certificates, CRLs, and cross-pair certificates) already conform to the X.500 standard attributes for storing certificates and CRLs and do not need to be changed.

Table 8.1. LDAP Publishers

Publisher Description
LdapCaCertPublisher Publishes CA certificates to the LDAP directory.
LdapCrlPublisher Publishes CRLs to the LDAP directory.
LdapDeltaCrlPublisher Publishes Delta CRLs to the LDAP directory.
LdapUserCertPublisher Publishes all types of end-entity certificates to the LDAP directory.
LdapCrossCertPairPublisher Publishes cross-signed certificates to the LDAP directory.

8.2.3.3. Creating Mappers

Mappers are only used with LDAP publishing. Mappers define a relationship between a certificate's subject name and the DN of the directory entry to which the certificate is published. The Certificate Manager needs to derive the DN of the entry from the certificate or the certificate request so it can determine which entry to use. The mapper defines the relationship between the DN for the user entry and the subject name of the certificate or other input information so that the exact DN of the entry can be determined and found in the directory.
When it is configured, the Certificate Manager automatically creates a set of mappers defining the most common relationships. The default mappers are listed in Table 8.2, “Default Mappers”.

Table 8.2. Default Mappers

Mapper Description
LdapUserCertMap Locates the correct attribute of user entries in the directory in order to publish user certificates.
LdapCrlMap Locates the correct attribute of the CA's entry in the directory in order to publish the CRL.
LdapCaCertMap Locates the correct attribute of the CA's entry in the directory in order to publish the CA certificate.

To use the default mappers, configure each of the macros by specifying the DN pattern and whether to create the CA entry in the directory. To use other mappers, create and configure an instance of the mapper. For more information, see Section C.2, “Mapper Plug-in Modules ”.
To modify a mapper:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Mappers.
    The Mappers Management tab, which lists configured mappers, opens on the right.
    Mappers Management Tab

    Figure 8.6. Mappers Management Tab


  3. In the mapper list, select a mapper to modify.
  4. To edit an existing mapper, click Edit/View. The editor window opens.
    Mapper Editor Window

    Figure 8.7. Mapper Editor Window


  5. To create a new mapper instance, click Add. The Select Mapper Plugin Implementation window opens, which lists registered mapper modules. Select a module, and edit it. For complete information about these modules, see Section C.2, “Mapper Plug-in Modules ”.
    Selecting a New Mapper Type

    Figure 8.8. Selecting a New Mapper Type


  6. Edit the mapper instance, and click OK.
    Creating a New Mapper

    Figure 8.9. Creating a New Mapper


    See Section C.2, “Mapper Plug-in Modules ” for detailed information about each mapper.

8.2.3.4. Creating Rules

After configuring the mappers for LDAP publishing, configure the rules for the published certificates and CRLs, as described in Section 8.2.4, “Creating Rules”.

8.2.4. Creating Rules

Rules determine what certificate object is published in what location. Rules work independently, not in tandem. A certificate or CRL that is being published is matched against every rule. Any rule which it matches is activated. In this way, the same certificate or CRL can be published to a file, to an Online Certificate Status Manager, and to an LDAP directory by matching a file-based rule, an OCSP rule, and matching a directory-based rule.
Rules can be set for each object type: CA certificates, CRLs, user certificates, and cross-pair certificates. The rules can be more detailed for different kinds of certificates or different kinds of CRLs.
The rule first determines if the object matches by matching the type and predicate set up in the rule with the object. Where matching objects are published is determined by the publisher and mapper associated with the rule.
Rules are created for each type of certificate the Certificate Manager issues.
Modify publishing rules by doing the following:
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing, and then Rules.
    The Rules Management tab, which lists configured rules, opens on the right.
    Rules Management Tab

    Figure 8.10. Rules Management Tab


  3. To edit an existing rule, select that rule from the list, and click Edit. This opens the Rule Editor window.
    Using the Rule Editor Window to Edit an Existing Rule

    Figure 8.11. Using the Rule Editor Window to Edit an Existing Rule


  4. To create a rule, click Add. This opens the Select Rule Plug-in Implementation window.
    Select Rule Plugin Implementation Window

    Figure 8.12. Select Rule Plugin Implementation Window


    Select the Rule module. This is the only default module. If any custom modules have been been registered, they are also available.
  5. Edit the rule.
    Rule Editor Window

    Figure 8.13. Rule Editor Window


    • type. This is the type of certificate for which the rule applies. For a CA signing certificate, the value is cacert. For a cross-signed certificate, the value is xcert. For all other types of certificates, the value is certs. For CRLs, specify crl.
    • predicate. This sets the predicate value for the type of certificate or CRL issuing point to which this rule applies. The predicate values for CRL issuing points, delta CRLs, and certificates are listed in Table 8.3, “Predicate Expressions”.
    • enable.
    • mapper. Mappers are not necessary when publishing to a file; they are only needed for LDAP publishing. If this rule is associated with a publisher that publishes to an LDAP directory, select an appropriate mapper here. Leave blank for all other forms of publishing.
    • publisher. Sets the publisher to associate with the rule.
Table 8.3, “Predicate Expressions” lists the predicates that can be used to identify CRL issuing points and delta CRLs and certificate profiles.

Table 8.3. Predicate Expressions

Predicate Type Predicate
CRL Issuing Point
issuingPointId==Issuing_Point_Instance_ID && isDeltaCRl==[true|false]
To publish only the master CRL, set isDeltaCRl==false. To publish only the delta CRL, set isDeltaCRl==true. To publish both, set a rule for the master CRL and another rule for the delta CRL.
Certificate Profile
profileId==profile_name
To publish certificates based on the profile used to issue them, set profileId== to a profile name, such as caServerCert.

8.2.5. Enabling Publishing

Publishing can be enabled for only files, only LDAP, or both. Publishing should be enabled after setting up publishers, rules, and mappers. Once enabled, the server attempts to begin publishing. If publishing was not configured correctly before being enabled, publishing may exhibit undesirable behavior or may fail.

NOTE

Configure CRLs. CRLs must be configured before they can be published. See Chapter 6, Revoking Certificates and Issuing CRLs.
  1. Log into the Certificate Manager Console.
    pkiconsole https://server.example.com:9445/ca
  2. In the Configuration tab, select Certificate Manager from the navigation tree on the left. Select Publishing.
    The right pane shows the details for publishing to an LDAP-compliant directory.
  3. To enable publishing to a file only, select Enable Publishing.
  4. To enable LDAP publishing, select both Enable Publishing and Enable Default LDAP Connection.
    Enabling Publishing

    Figure 8.14. Enabling Publishing


    In the Destination section, set the information for the Directory Server instance.
    • Host name. If the Directory Server is configured for SSL client authenticated communication, the name must match the cn component in the subject DN of the Directory Server's SSL server certificate.
      The hostname can be the fully-qualified domain name or an IPv4 or IPv6 address.
    • Port number.
    • Directory Manager DN. This is the distinguished name (DN) of the directory entry that has Directory Manager privileges. The Certificate Manager uses this DN to access the directory tree and to publish to the directory. The access control set up for this DN determines whether the Certificate Manager can perform publishing. It is possible to create another DN that has limited read-write permissions for only those attributes that the publishing system actually needs to write.
    • Password. This is the password which the CA uses to bind to the LDAP directory to which the certificate or CRL is published. The Certificate Manager saves this password in its password.conf file. For example:
      CA LDAP Publishing:password
      The parameter name which identifies the publishing password (CA LDAP Publishing) is set in the Certificate Manager's CS.cfg file in the ca.publish.ldappublish.ldap.ldapauth.bindPWPrompt parameter, and it can be edited.
    • Client certificate. This sets the certificate the Certificate Manager uses for SSL client authentication to the publishing directory. By default, the Certificate Manager uses its SSL server certificate.
    • LDAP version. Select LDAP version 3.
    • Authentication. The way the Certificate Manager authenticates to the Directory Server. The choices are Basic authentication and SSL client authentication.
      If the Directory Server is configured for basic authentication or for SSL communication without client authentication, select Basic authentication and specify values for the Directory manager DN and password.
      If the Directory Server is configured for SSL communication with client authentication, select SSL client authentication and the Use SSL communication option, and identify the certificate that the Certificate Manager must use for SSL client authentication to the directory.
The server attempts to connect to the Directory Server. If the information is incorrect, the server displays an error message.