This article describes how to create a distribution rule used in the Certificate Authority (CA) within Smart ID Certificate Manager (CM). This task is done in the Administrator's workbench (AWB) in Certificate Manager.

Certificates and CRLs are distributed to public locations after being issued. Each distribution rule defines the parameters for a single type of data and a single destination.

There are two types of protocols. LDAP and HTTP:

  • The LDAP protocol (default) distributes CRLs and certificates to an LDAP directory.
  • The HTTP protocol either pushes CRLs to the Nexus OCSP Responder or pushes certificates to web applications that support the application/pkix-cert content type.

Prerequisites

The following prerequisites apply:

  • Two administration officers must sign the request.
  • Both officers must have the following roles:
    • Use AWB
    • CA and Key tasks
  • A connection to the CM host must have been established (see Connect to a Certificate Manager host).

For LDAP

  • The following information is required by the administration officer during the task:
    • The rule name that will appear in the explorer bar
    • The host:port to be used
    • The directory user ID and password used by the CA to log in to the target server

    • The distinguished name required to point to the storage location in the directory

    • The object class and attributes that define the data to be stored in the above location

    • The update policy parameters

For HTTP

  • The following information is required by the administration officer during the task:
    • The rule name that will appear in the explorer bar
    • The host:port to be used
    • The user ID and password used by the CA to log in to the target server if authentication is required

Step-by-step instruction


Clicking Save at any time during the creation of the distribution rule, before clicking OK, will save the data and place the incomplete request in the Distribution rules sub-group..

To complete the creation of the distribution rule at a later stage:

  • Highlight the unsigned rule in the explorer bar.
  • Select Modify from the Edit menu, the toolbar, or the right-click shortcut menu.


For a normal distribution, all the fields of the Create Distribution Rule Request dialog are mandatory, including the selection of at least one Update policy option. The exception is if the Unpublish option is enabled.

To create a distribution rule:

  1. In AWB, select New > Distribution rule.

  2. In the Create Distribution Rule Request dialog, enter the Rule name that should appear in the Distribution rules sub-group in the explorer bar.

  3. Set the procedure State to Active or Closed as required.
  4. Select Domain and check Visible in subdomain if applicable.
  5. Select Protocol.
    1. If LDAP is selected, the rest of this procedure applies.
    2. If HTTP is selected, the appearance of the dialog changes and other parameters have to be specified, see section "Create distribution rule, HTTP protocol" below.

    3. For information regarding Unpublish, see below.

  6. Enter the address of the target server in the Host:Port field or select a host from the drop-down list of hosts used in other distribution rules. The address should consist of the IP address or host name and the port number.

  7. Set the LDAP over TLS parameter using the Yes and No option buttons.

    1. Select Yes if communication with the LDAP server is through TLS (LDAPS).

    2. The default is No.

  8. Enter the Directory user ID that will be used by the CA to log in to the target server.
  9. Enter the Password associated with the User ID entered in step 8.

  10. Click the + button associated with Distinguished Name to open the Select Distinguished Name window. The distinguished name points to the storage location in the directory.

  11. Enter a distinguished name attribute or select an attribute from the drop-down list in the window and click OK. A search filter can be specified as the last element in the list, note that the filter must be preceded with the string "??sub?". Repeat steps 10 and 11 until all the relevant attributes required to create the distinguished name have been entered.

  12. Enter the Object class of the certificate or CRL data that will be stored, or select an object class from the drop-down list of object classes used in other distribution rules.

    Warning
    The attributes selected in the following steps must be valid attributes of the selected Object class. Invalid attributes will result in a rejection from the directory server and a CM event log error.


  13. In Attributes, click + to open the Select object attributes window. The object class attributes and their values are the data that will be written in the target directory at the destination specified by the distinguished name.

  14. Enter an object attribute or select the required object attribute from the drop-down list in the window and click OK. Repeat steps 13 and 14 until all the relevant object attributes have been entered.

  15. Select the required Update policy using the check boxes. At least one check box must be selected.
    1. Create object - a new object, with all its attributes will be created in the target directory.

    2. Add attribute to object - a new attribute will be added to an existing object.

    3. Edit existing value - the existing value of an attribute will be modified.

  16. Click OK and sign the request. See Sign tasks in Certificate Manager for more information.

If an LDAP Proxy is needed, you may not configure it here. You must manually setup an LDAP Proxy that knows where to forward your LDAP distribution based on distinguished name.



When the Unpublish option in the LDAP protocol section is selected, the Create Distribution Rule Request dialog box will update, by removing irrelevant options. An unpublished distribution rule only requires the path to the certificate attribute to remove, specified in the Distinguished Name field.

Optionally, you can add or edit attributes during an 'unpublish' by specifying the Object class, Attribute and Update Policy sections.

  1. Do steps 10 and 11 from section "Create distribution rule, LDAP protocol" to build the path to the certificate directory attribute that should be removed.
  2. Specify the attribute name, which contains the certificate to be removed, by adding the following: ?<attribute_name> to the Distinguished Name. Example: ?userCertificate.

  3. Optional: Do steps 12 to 15 from section "Create distribution rule, LDAP protocol" if it is required to add or edit attributes in the LDAP entry.
  4. Click OK and sign the request. See Sign tasks in Certificate Manager for more information.


When the HTTP protocol is selected, the Create Distribution Rule Request dialog box changes its appearance.

  1. Enter User and Password to be used when logging on to the host.
  2. Specify the host address URL.

  3. Select type of Payload: CRL or Certificate.

  4. Select the kind of Encoding to be used for the contents: Base64 or binary.
  5. Click OK and sign the request. See Sign tasks in Certificate Manager for more information.

If a HTTP Proxy is needed, check Use Proxy and specify the Proxy HTTP URL. Note that HTTPS Proxy is not supported. If the destination host uses HTTPS, CM will create a tunnel through the Proxy and forward the encrypted communication to the destination host. This requires a Proxy that supports HTTP CONNECT tunneling.


Theory

A distribution rule request contains a varying number of fields depending on which protocol is selected.

  • The LDAP protocol is default and the corresponding dialog box is shown initially. The LDAP protocol section includes the Unpublish option. This option, when enabled, will try to remove the provided certificate from a specified attribute from the LDAP directory. The certificate attribute name must be specified in the Distinguished Name field to define its location in the AD, for example, ?userCertificate.
  • If HTTP is selected, another version of the dialog box appears, see section "Create distribution rule, HTTP protocol".


The distinguished name specifies the location in the directory information tree (DIT) where an object will be added or modified. The location of the object must either be specified as

  • the full distinguished name or
  • a base distinguished name and an LDAP search filter.

The distinguished name and search filter can be made up of either static or dynamic values (refer to the "Distribution Rules and Dynamic Information" chapter in the Technical Description). A dynamic value is a keyword placed within curly brackets, {keyword}, and is replaced with relevant information from the particular certificate or CRL. The syntax of a search filter is defined in A String representation of LDAP Search Filters, RFC 2254.

Syntax: location = dn ["?" [attribute] ["?sub?" filter]]

cn={cn}, ou={ou}, o={o}, c={c}
o={o}, c={c} ??sub?(&(objectClass=person)(cn={cn}))



  • The short names of the common attributes of the subject name in a certificate can be used as keys, that is, cn, l, ou, o and c.
  • Values in the subjectAltName extension can be used with the keys rfc822Name and userPrincipalName.

See the "Distribution Rules and Dynamic Information" chapter in the Technical Description for the full list of the dynamic data keys.