Netscape logo Administrator's Guide
Netscape Certificate Management System
Previous      Contents      Index      DocHome      Next     

Chapter 10   Authentication


This chapter discusses the authentication methods available in Netscape Certificate Management System (CMS) during the enrollment of end entities, and details how to set up those authentication methods.

This chapter contains the following sections:

Enrollment Overview

The process of enrolling end-entities involves the end entity submitting a request (or an agent submitting the request for the end entity), authenticating the end-entity, and verifying the request.

CMS provides four enrollment methods:

A Certificate Manager is initially configured for agent-approved enrollment and for CMCAuth; a Registration Manager is initially configured for agent-approved enrollment, CMCAuth, and for in person enrollment.

You can set up automated enrollment by enabling and configuring an instance of one of the authentication plug-in modules. You can also create plug-ins for automatic enrollment using other forms of authentication, such as a secure ID card or a relational database using the CMS SDK.

You configure authentication in the subsystem that actually processes end-entity requests. If you have set up a Registration Manager to process requests, you configure authentication in that Registration Manager. The Registration Manager does all of the authentication processing. The Registration Manager then sends a signed request to the Certificate Manager via a trusted connection. The Certificate Manager simply processes the request, it does not authenticate the user, or check that the user was authenticated.

You can configure more than one authentication method in a single instance of a subsystem. The HTML registration pages contain hidden values specifying the method used. If you were to set up multiple methods, you would create separate end-entity registration pages, each specifying a different method. If you use the certificate profile feature, the end-entity enrollment pages are dynamically generated for each certificate profile you configure and enable. The authentication method associated with this certificate profile is specified in the dynamically generated enrollment page.

How Authentication Works

An end entity submits a request for enrollment. The form or method used to submit the request identifies the method of authentication and enrollment. If the HTML end-entity interface is used to submit the request, the form used by the end entity to make the request contains hidden values that associate this form, and thus this submission, with an authentication method.

If the authentication method is an agent-approved enrollment, the end entity submits the request, which is then sent to the request queue of the agent services interface. If the automated notification for request in queue is set up, an email message is sent to the agent or agents set up to receive this message, informing them that a new request has been received.

The agent can change some aspects of the request depending on which aspects can be changed in the request form and the constraints set up in either the policies or certificate profiles set up. The agent can then reject the request, change the status of the request, or approve the request. The request must also pass the policies or certificate profiles set up for the Certificate Manager. If the subsystem where the request is submitted is a Registration Manager, the request must pass the policies and certificate profiles of both the Registration Manager and the Certificate Manager. Once the request is approved by an agent and passes the policies or certificate profiles, the certificate is issued. When the certificate is issued, it is stored in the internal database and can be retrieved by the end entity from the end-entity interface by serial number or by request Id.

If the enrollment method is an automated method, the end entity submits the request along with whatever information is needed to authenticate the user. Upon successful authentication of the user, the request is then processed without being sent to the agent's queue. If the request passes the policy or certificate profile configuration of the Certificate Manager, the request is processed and the certificate is issued. If the subsystem where the request is submitted is a Registration Manager, the request must pass the policies and certificate profiles of both the Registration Manager and the Certificate Manager. When the certificate is created, it is stored in the internal database and it is delivered to the end entity immediately via the HTML forms.

You can set up an automated notification for any method that sends an email to the end entity when the certificate is issued.

About Renewal

When an end entity requests a certificate renewal, the end entity presents its current certificate. The certificate itself is used to authenticate the user. The process for renewal is automatic; if the certificate is presented a new certificate is issued. There is no agent intervention in this process. You cannot customize the renewal process.

In order to renew, the following must be true:

You can set up the RenewalNotification job which sends email notifications to the end entity at preconfigured intervals before the expiration of their current certificate. See Chapter 14 "Automated Jobs" for details.

Dual-Key Pairs

Dual key pairs are a set of two private and public keys where one set is used for signing and one for encryption. CMS supports dual key-pairs allowing you to create them during enrollment, and allowing you to create two certificates, one for the signing key, and one for the encryption key. The dual key-pairs feature is only supported in CMS when using Netscape 7, or older versions of Netscape that work with Personal Security Manager.

To create dual-key pairs, and the resultant certificates associated with each key, you need to enable this function by changing the javascript found in the enrollment page. You use any method of authentication, chaining it to enable dual-key pairs by modifying the javascript on that enrollment page. There are instructions, presented as HTML comments, in the forms describing how to change the javascript. Basically, you need to add some lines to the javascript and you are ready to go.

When you set up dual-key pairs, you should check your policy or certificate profile set up and set your policies or certificate profiles to work correctly when generating separate certificates for signing and encryption.

Agent-Approved Enrollment

Both the Registration Manager and Certificate Manager are initially configured for agent-approved enrollment. An end entity makes a request which is then sent to the agent services interface for an agent's approval. An agent can change some aspects of the request, change the status of the request, reject the request, or approve the request. Once the request is approved, the signed request is sent to the Certificate Manager for processing. The Certificate Manager processes the request and issues the certificate.

The agent-approved enrollment method is not configurable. If you don't configure a Certificate Manager or Registration Manager for any other enrollment method, the server automatically sends all certificate-related requests to a queue where they await agent approval. This ensures that all requests that lack authentication credentials are sent to the request queue for agent approval.

Setting Up Agent-Approved Enrollment

To set up agent-approved enrollment you do the following:

Automated Enrollment

Automated enrollment is the method in which an end-entity enrollment request is processed upon the successful authentication of the end entity as defined by an instance of an authentication plug-in module; no agent intervention or approval is necessary. The following authentication plug-in modules are provided:

You can create custom plug-in modules for other methods of authentication using the CMS SDK. You must register and enable any custom plug-ins you create.

Setting Up Directory Based Enrollment

The UidPwdDirAuth and the UdnPwdDirAuth plug-in modules implement the directory-based authentication method. End users enroll for a certificate by providing their user IDs or DN, and their password for the authentication to an LDAP directory.

To set up directory based authentication you do the following:

Setting Up the UidPwdDirAuth or UdnPwdDirAuth Authentication

To set up one of these two methods of authentication:

  1. In the CMS window of the Certificate Manager or Registration Manager that processes certificate requests, select the Configuration tab.
  2. Select Authentication in the navigation tree.
    3. The right pane shows the Authentication Instance tab listing currently configured authentication instances.
     
  3. Click Add.
    4. The Select Authentication Plug-in Implementation window appears.
     
  4. Select UidPwdDirAuth for authentication based on user ID and password, select UdnPwdDirAuth for authentication based on DN and password.
  5. Click Next.
    6. The Authentication Instance Editor window appears.
     
  6. Fill in the following fields in the Authentication Instance Editor window:
    7. Authentication Instance ID. Accept the default instance name, or enter a new name. If you choose to use a different name, be sure to edit this name in the hidden value in the enrollment forms.
     
    dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN. See DNs in Certificate Management System.
     
    ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token—that is, values retrieved from this parameter can be used by policy modules to formulate subject names for certificates or to make other policy decisions. For details, see SubjectAltNameExt. Entering values for this parameter is optional.
     
    ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules—that is, values retrieved from this parameter can be used by policy modules to make certain policy decisions or to add additional information to users' certificates.
     
    For example, assume you have defined an LDAP binary attribute for storing users' pictures or fingerprints in your directory. You could develop a policy plug-in that adds users' pictures to their certificates as extensions.
     
    Entering values for this parameter is optional.
     
    ldap.ldapconn.host. Specifies the fully-qualified DNS host name of the authentication directory.
     
    ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests from CMS.
     
    ldap.ldapconn.secureConn. Specifies the type—SSL or non-SSL—of the port on which the authentication directory listens to requests from CMS. Select if this is an SSL port, deselect if this is a non-SSL port.
     
    ldap.ldapconn.version. Specifies the LDAP protocol version. 2 specifies LDAP version 2. If your authentication directory is based on Netscape Directory Server 1.x, choose 2. 3 specifies LDAP version 3. For Directory Server versions 3.x and later, choose 3 (default).
     
    ldap.basedn. Specifies the base DN for searching the authentication directory—the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.
     
    ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. Permissible values: 1 to 3.
     
    ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. Permissible values: 3 to 10.
     
  7. Click OK. The authentication instance is now set up and enabled.

Setting Up Pin Based Enrollment

Pin based authentication involves setting up pins for each of your users in the LDAP directory, distributing those pins to your users, and then having the users provide their pin along with their user ID and password when they fill out a certificate request. Users are then authenticated both against an LDAP directory using their user ID and password, and against the pin that is contained in their LDAP entry. When the user successfully authenticates, their request is automatically processed and a new certificate is issued.

CMS provides a tool that will add the need schema for pins to the Directory Server, and generate the pins for each user.

To set up pin based authentication you do the following:

Creating Pins

The pin tool performs the following functions:

The pin tool is located in the following directory:

<server_root>/bin/cert/tools

This tool comes with its own documentation in this location, and is also documented in the CMS Command-Line Tools Guide.

To use the pin tool:

  1. Go to the following directory:
    2. <server_root>/bin/cert/tools
     
  2. Open the setpin.conf file in a text editor.
  3. Follow the instructions outlined in the file and make the appropriate changes.
    4. Typically, you will need to update the Directory Server's host name, Directory Manager's bind password, and PIN manager's password.
     
  4. Run the setpin command with its optfile option pointing to the setpin.conf file (setpin optfile=setpin.conf).
    5. The tool modifies the schema with a new attribute (by default, pin) and a new object class (by default, pinPerson), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.
     
  5. If you want to generate PINs for specific user entries, or want to provide your own PINs, you can add these pins using an input file. For information on constructing an input file, see the PIN Generator documentation.
  6. Run the setpin command to create hashed pins in the directory.
    7. You can run the tool first without the write option to generate a list of pins without actually changing the directory.
     
    For example:
     
    ./setpin host=yourhost port=9446 length=11 input=infile output=outfile write "binddn=cn=pinmanager,o=example.com" bindpw="netscape" basedn=o=netscape.com "filter=(uid=u*)"
     
  7. Use the output file for delivering PINs to users after you complete setting up the required authentication method.

After you have confirmed that the PIN-based enrollment works, deliver the PINs to users so they can use them during enrollment. To protect the privacy of PINs, be sure to use a secure, out-of-band method for delivery.

Policy Setup for Replicated Directories

If your directory is replicated, pins may not be removed from the replicas for some period after they have been removed from the master. The removal of the pins from the replica does not occur until it is updated by the master. During this time period, a user could theoretically apply for another certificate if the replica is used to authenticate the user.

To avoid this problem, you need to enable the AttributePresentConstraints policy in the Certificate Manager that actually issues the certificates; see AttributePresentConstraints. This policy forces the Certificate Manager to check the master directory before issuing the certificate. If the Registration Manager uses a Directory Server replica to authenticate users, and the user successfully authenticates to a replica that still contains the pin, the Certificate Manager will reject the request when this policy is enabled since the Certificate Manager checks the master directory in which the pin has been removed.

Setting Up the UidPwdPinDirAuth Authentication

To setup this method of authentication:

  1. In the CMS window of the Certificate Manager or Registration Manager that processes certificate requests, select the Configuration tab.
  2. Select Authentication in the navigation tree.
    3. The right pane shows the Authentication Instance tab listing currently configured authentication instances.
     
  3. Click Add.
    4. The Select Authentication Plug-in Implementation window appears.
     
  4. Select the UidPwdPinDirAuth plug-in module.
  5. Click Next.
    6. The Authentication Instance Editor window appears.
     
  6. Fill in the following fields in the Authentication Instance Editor window:
    7. Authentication Instance ID. Accept the default instance name, or enter a new name. If you chose to use a different name, be sure to edit this name in the enrollment forms.
     
    removePin. Specifies whether to remove PINs from the authentication directory after end users successfully authenticate. Removing PINs from the directory restricts users from enrolling more than once, and thus prevents them from getting more than one certificate. Select if you want to remove PINs providing the bindDN and password of the pin manager.
     
    pinAttr. Specifies the authentication directory attribute for PINs. If you used the PIN Generator utility, the attribute is specified by the value of the objectclass parameter; the default value for this parameter is pin.
     
    dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN. See DNs in Certificate Management System.
     
    ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token—that is, values retrieved from this parameter can be used by policy modules to formulate subject names for certificates or to make other policy decisions. For details, see SubjectAltNameExt. Entering values for this parameter is optional.
     
    ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules—that is, values retrieved from this parameter can be used by policy modules to make certain policy decisions or to add additional information to users' certificates.
     
    For example, assume you have defined an LDAP binary attribute for storing users' pictures or fingerprints in your directory. You could develop a policy plug-in that adds users' pictures to their certificates as extensions.
     
    Entering values for this parameter is optional.
     
    ldap.ldapconn.host. Specifies the fully-qualified DNS host name of the authentication directory.
     
    ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests from CMS.
     
    ldap.ldapconn.secureConn. Specifies the type—SSL or non-SSL—of the port on which the authentication directory listens to requests from CMS. Select if this is an SSL port, deselect if this is a non-SSL port.
     
    ldap.ldapconn.version. Specifies the LDAP protocol version. 2 specifies LDAP version 2. If your authentication directory is based on Netscape Directory Server 1.x, choose 2. 3 specifies LDAP version 3. For Directory Server versions 3.x and later, choose 3 (default).
     
    ldap.ldapauth.bindDN. Specifies the user entry to bind as when removing PINs from the authentication directory. You need to specify this parameter only if you've selected removePin. It is recommended that you create and use a separate user entry that has permission to modify only the PIN attribute in the directory. For example, don't use the directory manager's entry as it has privileges to modify the entire directory content.
     
    password. Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter. when you save your changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups.You need to specify this parameter only if you've selected removePin.
     
    ldap.ldapauth.clientCertNickname. Specifies the nickname of the certificate to be used for SSL client authentication to the authentication directory in order to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory's certificate database, and that the authentication directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory. (This is needed for PIN removal only.)
     
    ldap.ldapauth.authtype. Specifies the authentication type—basic authentication or SSL client authentication—required in order to remove PINs from the authentication directory.
     
    ldap.basedn. Specifies the base DN for searching the authentication directory—the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.
     
    ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory.Permissible values: 1 to 3.
     
    ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory.Permissible values: 3 to 10.
     
  7. Click OK. The authentication instance is now set up and enabled.

Setting Up Portal Enrollment

Portal enrollment enables you to issue certificates and create directory entries for users who do not yet have an entry in your directory. Portal enrollment involves registering users by adding them to your directory while simultaneously issuing them a certificate. When a user requests a certificate, the information they provide is used to add the user to the directory, if an entry does not presently exist for that user, and to issue the user a certificate. Portal enrollment is useful when you have a portal and want to register users and have them later authenticate using a certificate. Since you register anyone who comes to the site, this method does not provide any authentication of users when you enroll them, unless they already have entries in the LDAP directory. It provides authentication, in the form of their LDAP entries and certificates when they log into the site proving only that they are registered users.

The PortalEnroll module does the following:

Note that the portal authentication module by default uses the standard LDAP object class named inetOrgPerson to create and update user entries. The input fields defined in the default portal enrollment form correspond to the attributes defined in this object class as defined in Netscape Directory Server 4.x. The module is capable of reading and writing these attributes only. However, you can customize the module to accommodate all the fields supported by popular portals by extending the directory schema to include a new object class; you'll also be required to update the enrollment form to include attributes corresponding to the new object class.

To set up portal enrollment you do the following:

Setting Up the PortalEnroll Authentication

To setup this method of authentication:

  1. In the CMS window of the Certificate Manager or Registration Manager that processes certificate requests, select the Configuration tab.
  2. Select Authentication in the navigation tree.
    3. The right pane shows the Authentication Instance tab listing currently configured authentication instances.
     
  3. Click Add.
    4. The Select Authentication Plug-in Implementation window appears.
     
  4. Select the PortalEnroll plug-in module.
  5. Click Next.
    6. The Authentication Instance Editor window appears.
     
  6. Fill in the following fields in the Authentication Instance Editor window:
    7. Authentication Instance ID. Accept the default instance name, or enter a new name. If you chose to use a different name, be sure to edit this name in the enrollment forms.
     
    dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN. See DNs in Certificate Management System.
     
    ldap.ldapconn.host. Specifies the fully-qualified DNS host name of the authentication directory.
     
    ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests from CMS.
     
    ldap.ldapconn.secureConn. Specifies the type—SSL or non-SSL—of the port on which the authentication directory listens to requests from CMS. Select if this is an SSL port, deselect if this is a non-SSL port.
     
    ldap.ldapconn.version. Specifies the LDAP protocol version. 2 specifies LDAP version 2. If your authentication directory is based on Netscape Directory Server 1.x, choose 2. 3 specifies LDAP version 3. For Directory Server versions 3.x and later, choose 3 (default).
     
    ldap.ldapauth.bindDN. Specifies the user entry to bind as when adding entries to the LDAP directory. This user must have permission to create entries in the directory.
     
    password. Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter. when you save your changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups.
     
    ldap.ldapauth.clientCertNickname. Specifies the nickname name of the certificate to be used for SSL client authentication to the authentication directory in order to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory's certificate database, and that the authentication directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory. (This is needed for PIN removal only.)
     
    ldap.ldapauth.authtype. Specifies the authentication type—basic authentication or SSL client authentication—required in order to remove PINs from the authentication directory.
     
    ldap.basedn. Specifies the base DN for searching the authentication directory—the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment from) and the base DN to construct an LDAP search filter.
     
    ldap.objectclass. Specifies the object class to modify or update in the portal directory. Permissible values: Must be inetOrgPerson for the default portal enrollment form.
     
    ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. Permissible values: 1 to 3.
     
    ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. Permissible values: 3 to 10.
     
  7. Click OK. The authentication instance is now set up and enabled.

Setting Up CMC Enrollment

Note: The enrollment method described here will return Javascript rather than a CMC response. This information has been deprecated. See Setting Up a CMC Client for the latest information.

CMC enroll allows you to set up your own enrollment client, sign the certificate request with your agent certificate, and then send the signed request to the Certificate Manager. When this method is setup, the Certificate Manager will automatically issue certificates when a valid request signed with the agent certificate is received.

The CMCAuth authentication plug-in also activates CMC Revoke. CMC Revoke allows you to set up your own revocation client, sign the certificate request with your agent certificate, and then send the signed request to the Certificate Manager. When this method is setup, Certificate Manager will automatically revoke certificates when a valid request signed with the agent certificate is received.

To set up CMC enroll you do the following:

Setting Up the CMCAuth Authentication Plug-in

Note: This method of authentication is setup by default. You only need to perform the following procedure if you deleted the instance that was set up by default.

To setup this form of authentication:

  1. In the CMS window for the Certificate Manager issuing the certificates, select the Configuration tab.
  2. Select Authentication in the navigation tree.
    3. The right pane shows the Authentication Instance tab listing currently configured authentication instances.
     
  3. Click Add.
    4. The Select Authentication Plug-in Implementation window appears.
     
  4. Select the CMCAuth plug-in module.
  5. Click Next.
    6. The Authentication Instance Editor window appears.
     
  6. If you don't want to use the default instance name, in the Authentication Instance ID field, type a unique name for this instance that will help you identify it. If you chose to use a different name, be sure to edit the default name in the enrollment forms.
    7. There are no configuration options for this plug-in; it simply enables this functionality.
     
  7. Click OK. The authentication instance is now set up and enabled.

CMC Enroll Utility

The CMC Enroll utility, CMCEnroll, is used to sign a certificate request with an agent's certificate. It is installed along with CMS and is available in the following directory:

<server_root>/bin/cert/tools

This utility has the following syntax:

CMCEnroll -d<directory_containing_agent_cert> -h<db_password> -n<the certificate_common_name> -r<certificate_request_file> -p<certificate_DB_passwd> [-c]

where

-d

The location of the directory containing the cert8.db, key3.db, and secmod.db files associated with the agent certificate.

-h

Password to the database specified in the -d option.

-n

The common name of the certificate.

-r

The file name of the certificate request.

-p

The password to the browser certificate database.

-c

To optionally include any comments about the request.

Note: Surround values that include spaces in quotation marks.

Enable the End Entity pages for CMC Enrollment

You submit signed requests to the Certificate Manager by submitting them directly to the Certificate Manager. You can also submit them using the end-entity interface of the Certificate Manager or a Registration Manager. CMS provides a CMC Enrollment form called CMCEnrollment.html. The default configuration of this form does not include the field needed to paste your enrollment request. If you want to use this form to submit requests, you must change the configuration so that this field is available.

To enable the CMC Enrollment form for the end-entity interface of a Certificate Manager:

  1. Go to the directory <server-root>/cert-<instance>/web-apps/ee/ra.
  2. Open the file CMCEnrollment.html.
  3. Find the following line:
    4. <form method="post" action="/enrollment" onSubmit="return validate(document.forms[0])">
     
  4. Add the following line below the line you just found:
    5. <input type="hidden" name="authenticator" value="CMCAuth">
     

To enable the CMC Enrollment form for the end-entity interface of a Registration Manager:

  1. Go to the directory <server-root>/cert-<instance>/web-apps/ee/ra.
  2. Open the file CMCEnrollment.html.
  3. Find the following line:
    4. <form method="post" action="/enrollment" onSubmit="return validate(document.forms[0])">
     
  4. Add the following line below the line you just found:
    5. <input type="hidden" name="authenticator" value="CMCAuth">
     

Testing CMCEnroll

  1. Enable CMCEnroll.
  2. Create a certificate request. You can use the certutil tool found in the following directory to create the request:
    3. <server_root>/bin/cert/tools
     
  3. Copy the pkcs10 ascii output to a text file.
  4. Go to the following directory:
    5. <server_root>/bin/cert/tools
     
  5. Type the following command:
    6. CMCEnroll -d<directory_containing_agent_cert> -n<the certificate_common_name> -r<certificate_request_file> -p<certificate_DB_passwd>
     
    For example, if the input file created in step 3 is called request34.txt, your agent's certificate is stored in the directory /netscape/certs, the certificate common name of your agent's certificate for this CA is CertificateManagerAgentsCert, and your password for the certificate database is 1234pass, the command would look as follows:
     
    CMCEnroll -d"/netscape/certs" -n"CertificateManagerAgentsCert" -r /export/requests/request34.txt -p 1234pass
     
    The output of this command is stored in a file with the same filename and .out appended to the filename.
     
  6. Enable the end entity page for this feature. See Enable the End Entity pages for CMC Enrollment.
  7. Submit your signed certificate using the end entity port.
    1. Go the End Entity port.
    2. Select CMC Enrollment from the main end entity page.
    3. Paste the content of the output file into the first text area of this form.
    4. Remove "-----BEGIN NEW CERTIFICATE REQUEST-----" and "----END NEW CERTIFICATE REQUEST-----" from the pasted content.
    5. Select Certificate Type User Certificate, fill in the contact information, and submit the form.
  8. The certificate will be immediately processed and returned since a signed request was sent, and the CMCAuth plug-in was enabled.
  9. Use the agent page to search for the new certificates.

Note: With Netscape 4.x, the browser will return the message "the private key is not available". With Netscape 7.x, the browser will return "Your certificate has been imported into the browser!". In both cases, regardless of the return messages the certificate is not actually imported into the browser because we generated the certificate request outside of the browser in step 2 and it does not have this private key.

Agent Initiated End User Enrollment

The Registration Manager is enabled for in person enrollment of end users. The end user goes to the Registration Manager agent, who then processes the enrollment request. The Registration Manager agent authenticates the user through some physical means, such as a passport or drivers licence, and then the agent fills in the enrollment form for the end user and processes the request. This method of enrollment is called agent-initiated-end-user enrollment, face-to-face enrollment, or in-person-certificate enrollment.

The authentication plug-in AgentDirEnrollment, created during the installation of the Registration Manager, enables agent-initiated-end-user enrollment. The AgentDirEnrollment plug-in is an instance of the HashAuth plug-in. You can turn this feature off by disabling or deleting the AgentDirEnrollment instance.

CMS provides the following form for agent-initiated-end-user enrollment: <server_root>/cert-<instance_id>/web-apps/ee/ra/hashDirUserEnroll.template

The enrollment form works in conjunction with the authentication plug-in. The plug-in must be enabled for this form to work.

Setting Up Agent Initiated Enrollment

To set up in person enrollment you do the following:

Certificate-Based Enrollment

Note: This feature is supported only in legacy enrollment. CMS supports certificate-based enrollment for browser certificates. End users can use preissued certificates to authenticate to the server in order to enroll for certificates. The following are two deployment scenarios that explain the usefulness of certificate-based enrollment:

Setting Up Certificate Based Enrollment

General guidelines to set up certificate-based enrollment are as follows:

Issuing and Managing Server Certificates

CMS can issue SSL server certificates to servers. Servers use these certificates to authenticate themselves to other servers and end users, and to encrypt data. In order to issue SSL server certificates, the signing certificate for the Certificate Manager must be enabled for such issuance. If the Certificate Manager got its signing certificate from a third-party, the signing certificate may not allow for issuance of SSL server certificates.

For CMS to generate a server certificate, it must receive the certificate signing request (CSR) from the server that needs the certificate. This request must be initiated by the administrator of the specific server requiring the certificate.

SSL-enabled servers (or servers that are capable of using certificates for security) provide mechanisms for generating a CSR based on new or existing key pairs.

Once an administrator generates a CSR for a server, they must paste it into the appropriate server enrollment form hosted by a Registration Manager or Certificate Manager, and then submit the request.

The request is processed using the enrollment method associated with the request form. The server administrator goes to the agent-approved enrollment form hosted by the Registration Manager, pastes in the certificate signing request in PKCS #10 format, completes the other information in the enrollment form, and submits the form. The request is then processed according to that method.

The certificate profile feature offers an automated sever enrollment. Using this certificate profile, an agent makes the request for the SSL server certificate in the certificate profile and is authenticated using their agent certificate. If the agent is authenticated, the SSL server certificate request is automatically processed, and the issued certificate is returned to the agent via an HTML form.

Renewal of Server Certificates

Every certificate issued by CMS has a validity period that determines its expiration date. The validity period of a certificate is determined by the validity constraints policy settings at the time the certificate was issued, see "ValidityConstraints". To be valid beyond its expiration date, it must be renewed. Otherwise, the certificate becomes invalid, and the entity owning the certificate will no longer be able to use it. Also, the expired certificate will take up space in your publishing directory and in the internal database of CMS.

CMS allows server administrators to renew their certificates by using the server enrollment form hosted by a Certificate Manager or Registration Manager. The renewal process is similar to the enrollment process in that the administrators must manually generate the certificate-signing request using the server's key pair, paste that request in the agent-approved enrollment form, and submit the request.

Getting Certificates for Netscape Version 4.x and Later Servers

For Netscape version 4.x servers, you can use the Certificate Setup Wizard provided by Netscape Console to get new certificates, renew existing certificates, and install certificates in the database of a server. For information about this wizard, see Managing Servers with Netscape Console.

Note that there are two ways in which you can submit the certificate signing request to CMS:

When the wizard generates the certificate signing request for the key size and type you specified, you're presented with the opportunity to choose how you want to submit the request to the CA. The choices include the following:

To CA's email address. This option allows you to send the CSR to the CA administrator's email address. The administrator will then be required to submit the request to the CA by pasting the CSR in the CA's server enrollment form.
 
To CA's URL. This option allows you to submit the CSR to the CA directly. To submit the CSR to the Certificate Manager, you should enter, depending on the end-entity port you want to use, either of the following URL:
 
http://<CA's_hostname>:<end_entity_port>/enrollment or
https://<CA's_hostname>:<end_entity_SSL_port>/enrollment
 
Note that the request submitted to the CA's URL gets queued for approval by the Certificate Manager agent.
 

To submit the server certificate request to CMS manually:

  1. Open a web browser window.
  2. Go to the End Entity Services interface of the Certificate Manager (or a Registration Manager that's connected to the Certificate Manager) by entering either of these URLs:
    3. https://<hostname>:<end_entity_HTTPS_port> or http://<hostname>:<end_entity_HTTP_port>
     
  3. In the left frame, select List Certificate Profiles. Click on Manual Server Certificate Enrollment.
  4. In the server-enrollment form that appears, enter the required information:
    5. Certificate Request Type. Choices of PKCS#10, CRMF, CMC.
     
    Certificate Request. Paste the base-64 encoded blob, including the -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- marker lines, you copied to the text file earlier.
     
    Requestor Name. Type your name.
     
    Requestor Email. Type your business email address, for example, jdoe@someCompany.com.
     
    Requestor Phone. Type your business phone number.
     
    Additional Comments. Type any information that will help you identify this request in the future or will help the person who will process this request.
     
  5. Click Submit.

CEP Enrollment

Note: This feature is supported in legacy enrollment only. CMS can issue certificates to a wide variety of entities, such as web browsers, SSL-enables servers, routers, virtual private network (VPN) clients, and so on. This section explains how you can configure CMS to issue router and VPN-client certificates.

About CEP Enrollment

Cisco routers support the use of certificates for authentication, encryption, and tamper detection by using the IP Security (IPSec) protocol. CMS supports Cisco's PKI protocol, the Certificate Enrollment Protocol (CEP); this protocol runs over HTTP and provides its own form of encryption. For an overview of certificate authority support for IPSec, see the information available at this URL: http://www.cisco.com/warp/public/cc/cisco/mkt/security/
encryp/prodlit/821_pp.htm

You can issue certificates to routers and CEP-compliant Virtual Private Network (VPN) clients using CMS. Routers use certificates to authenticate each other and to establish an encrypted IPSec channel between them; all TCP/IP communication passes through this encrypted channel.

CMS is set up to support issuance of certificates to routers and VPN clients using the CEP-based enrollment. The CEP enrollment URL is in the following form:

http://<DNS hostname>:<HTTP_port>/cgi-bin/pkiclient.exe

Note that older routers may require that the port associated with this enrollment is the default web server port, port 80.

In order to publish these certificates to an LDAP-compliant directory, you need to perform some additional configuration to accommodate the needs of routers and VPN clients, which need to retrieve certificates and CRLs via LDAP.

Setting Up Automated CEP Enrollment

You can configure the Certificate Manager to use either the challenge password or the subject name (all or a part of it) as an authentication token during a CEP enrollment, thus enabling users to get router certificates without any action on the part of the Certificate Manager agent.

CMS does not install an authentication module for CEP enrollment, but does provide a sample along with the CMS SDK that you can register and then configure, named FlatFileAuth.

This plug-in uses a file, called an authentication token, containing information that will be provided by the enrollee to uniquely identify it, and the password created for the enrollee that they present during enrollment to authenticate themselves.

To set this up, you must create the authentication-token file, and register and configure the plug-in. See "Authentication-Token File" and "Setting Up the CEP Plug-In".

Authentication-Token File

You create a text file with CEP-enrollee information that is used by the plug-in to authenticate the entity. The format of the authentication-token file is as follows:

<attribute>: <value>
<attribute>: <value>
...
<attribute>: <value>
<attribute>: <value>

Each enrolling user is represented by a sequence of attribute-value pairs, terminated by a blank line or end-of-file (EOF). The attributes can be any part of the subject name from the request, for example SERIALNUMBER, UNSTRUCTUREDADDRESS, CN, OU, UID, or the challenge password (pwd). These attributes are described as follows:



UNSTRUCTUREDNAME

 

Specifies the DNS name of the router (for example, router32.example.com). This is always specified in the request.

 

UNSTRUCTUREDADDRESS

 

Specifies the IP address of the router (for example, 101.22.33.124). This may not be in the request—a user may not want to include this in the subject name of the router certificate, and hence choose not to specify one during enrollment.

 

SERIALNUMBER

 

Specifies the serial number of the router (for example, 239333). This can sometimes be found on a label on the back of the router. It is also available by typing the show version command. This may not be in the request—a user may not want to include this in the subject name of the router certificate, and hence choose not to specify one during enrollment.

 

pwd

 

A password you create for the enrollee, give to the enrollee to be used in the certificate request to authenticate the enrollee.

 


The following is an example of completed entries in the file:

DN: <DN_for_user1>
UNSTRUCTUREDNAME: router32.example.com
UNSTRUCTUREDADDRESS: 101.22.33.124
SERIALNUMBER: 239333
pwd: ff93Kd

DN: <DN_for_user1>
UNSTRUCTUREDNAME: router33.example.com
UNSTRUCTUREDADDRESS: 101.22.33.125
SERIALNUMBER: 233455
pwd: 35pww3a

Note that if you specify a DN for a CEP enrollee in the authentication file, the Certificate Manager replaces the subject name requested by that user (router or VPN client) with the one specified in the file.

Setting Up the CEP Plug-In

To add and configure this plug-in:

  1. Get the plug-in from the CMS SDK. See the SDK documentation for information about this plug-in and any additional programming you may need to do to it.
  2. Register the plug-in the CMS authentication framework. See the CMS SDK for details on registering plug-ins.
  3. Register the plug-in in the CMS console. See "Managing Authentication Plug-ins" for instructions.
  4. Create an instance of the plug-in and configure it:
    1. In the CMS window of the Certificate Manager or Registration Manager that processes certificate requests, select the Configuration tab.
    2. Select Authentication in the navigation tree.
    The right pane shows the Authentication Instance tab listing currently configured authentication instances.
     
    1. Click Add.
      2. The Select Authentication Plug-in Implementation window appears.
       
    2. Select the FlatFileAuth plug-in module.
    3. Click Next.
      4. The Authentication Instance Editor window appears.
       
    4. Fill in the following fields in the Authentication Instance Editor window:
      5. authName. Provides a reference to the auths.instance authentication plug-in described in the auths.instance.* configuration parameters. If you want to turn off automated enrollment for CEP-based requests, delete this parameter from the configuration file.
       
      fileName. Specifies the filename of an authentication-token file. Be sure to use the full path name.
       
      keyAttributes. Specifies a comma-separated list of attributes in the request which together, uniquely identify an entry in the authentication-token file. The list of attributes you specify here must be contained in the authentication-token file, and they must be present in the request. The plugin then verifies the attributes provided in the request against those contained in the authentication-token file. Your choices for this value are: UNSTRUCTUREDNAME, UNSTRUCTUREDADDRESS, and SERIALNUMBER.
       
      authAttributes. Specifies a comma-separated list of attributes from the CEP request which must match the attributes specified in the authentication-token file for authentication to succeed. Currently the most useful thing to put in this parameter is pwd, the challenge password from the request.
       
      deferOnFailure. Specifies whether the server should defer CEP requests that fail authentication. true specifies that the server should defer CEP-enrollment requests that fail authentication; the deferred requests get queued for agent approval. false specifies that the server should reject CEP-enrollment requests that fail authentication.
       

Setting Up Multiple CEP Services

This step is optional.

By default, the CEP service runs on this URL: /cgi-bin/pkiclient.exe

It is possible to set up multiple instances of CEP, each with a different configuration, each listening on a different URL. This is useful if you have different requirements for different types of users. For example, you might want to have one CEP service that authenticates routers and publishes their certificates to the directory and another CEP service that authenticates VPN clients but does not publish their certificates to the directory.

To set up multiple CEP services, use the following example as a guide.

## Router configuration
   eeGateway.cep.cep1.appendDN=O=*BASE_DN*
   eeGateway.cep.cep1.createEntry=true
   eeGateway.cep.cep1.entryObjectClass=cep
   eeGateway.cep.cep1.url=/cgi-bin/pkiclient.exe
   eeGateway.cep.cep1.authName=flatfile_router

## VPN configuration
   eeGateway.cep.cep2.url=/vpnenroll
   eeGateway.cep.cep2.authName=flatfile_VPN

## Router authentication parameters in the configuration file
   auths.instance.flatfile_router.fileName=
      <full_path_to_the_authentication_file>
   auths.instance.flatfile_router.authAttributes=pwd
   auths.instance.flatfile_router.keyAttributes=UNSTRUCTUREDNAME
   auths.instance.flatfile_router.pluginName=flatfile
   auths.instance.flatfile_router.deferOnFailure=true

## VPN authentication parameters in the configuration file
   auths.instance.flatfile_VPN.fileName=
      <full_path_to_the_authentication_file>
   auths.instance.flatfile_VPN.authAttributes=pwd
   auths.instance.flatfile_VPN.keyAttributes=CN,OU,O
   auths.instance.flatfile_VPN.pluginName=flatfile
   auths.instance.flatfile_VPN.deferOnFailure=false

## FlatFileAuth plugin registered in the configuration file
   auths.impl.flatfile.class=com.netscape.certsrv.authentication.
      FlatFileAuth

When setting up multiple CEP services, you can use the cepsubstore attribute to differentiate one CEP service from another. For example, if you're setting up separate CEP services for router and VPN-client certificates and want to set different extensions in these certificates, you can make that happen with the help of predicates.

Setting Up Publishing of CEP Certificates and CRLs

Set up the Directory for Publishing CEP Certificates and CRLs

You need to do the following to set up the directory to publish CEP Certificates and CRLs:

Configure the Certificate Manager for Publishing Certificates and CRLs

In this step, you configure the Certificate Manager to issue router and VPN-client certificates with CRL Distribution Point Extension and to publish the certificates to a directory.

Certificate Issuance to Routers or VPN Clients

In general, issuing a certificate to a router involves the following steps:

  1. Note or print the certificate fingerprint information of the Certificate Manager CA signing certificate. You will be required to compare this with the fingerprint the router will show on the screen.
    2. To locate the fingerprint information:
     
    1. Go to the end-entity page hosted by the Certificate Manager.
    2. Click the Retrieval tab.
    3. List or search for the CA signing certificate.
    4. Click Details.
    5. Scroll down to the section that says "Certificate fingerprint."
  2. In your router documentation, locate the information specific to requesting certificates for routers. Check the signing algorithm, such as RSA or DSA, and key lengths, such as 512 and 1024, supported by the router. Based on that information, determine the signing algorithm and the key length for the certificate you want to request.
  3. Find out the password that enables you to access the router in privileged mode.
  4. In your router documentation, locate instructions for requesting certificates. You will be required to run the appropriate commands using this documentation.
  5. Generate the Key Pair for the Router
    6. Run the appropriate commands for your router, and generate the key pair. You will be required to provide the signing algorithm, such as RSA or DSA, and the key length, such as 512 or 1024. The longer the key length, the more time the router takes to generate the key pair.
     
  6. Request the CA's Certificate
    7. In this part of the operation, you identify the CA to the router, thus enabling the router to authenticate the CA from which it will request the certificate. You also verify whether the router is talking to the right CA; you do this manually.
     
    Here's what you should do:
     
    1. Run the appropriate command to get the CA certificate.
      2. The command will ask you to specify the following:
       
      —An identity for the CA. You can give any identity; choose something you will remember, since you will be required to provide it when you submit the certificate request.
       
      —The CA's enrollment URL; this is the enrollment URL you identified in Step 1.
       
    2. The router gets the CA certificate and displays its fingerprint on your screen.
    3. Verify the fingerprint on your screen with the one you noted down in
      Step 1.
      4. If it matches, the router is talking to the right CA.
       
  7. Submit the Certificate Request to the CA
    8. To submit the certificate request to the CA:
     
  8. Run the appropriate command.
    9. The command will ask you for certain information:
     
    The CA's identity. You specified this in Step 3.
     
    Challenge password. If you enter one, write it down; you will be required to specify this password to revoke the certificate.
     
    The CEP enrollment URL.
     
    Whether you want to include the router's serial number in the request. If you choose to include the serial number, it will be included in the certificate's subject name.
     
    Whether you want to include the router's IP address in the request. If you choose to include the IP address, it will be included in the certificate's subject name.
     
  9. If the CA to which the router submitted the request employs automatic enrollment (or authentication) for routers, the request will get processed by the CA. The CA may return the certificate to the router in the same transaction. If it doesn't, the router checks with the CA at periodic intervals; in the router configuration you can specify how often the router should poll the CA for the certificate and how many attempts it should make. By default, the router checks the CA every minute.
  10. If the CA to which you submitted the request is configured for agent-approved enrollment (or authentication), the request gets queued and awaits approval by an agent.

    11. Note  

    Your router may require additional configuration changes. Be sure to follow the information in your router documentation.



Example

The example below shows the commands and associated outputs for a Cisco router:

# To perform certificate enrollment for a router using CEP, you must be
# in privileged mode, which you do by typing "enable" first, and then
# entering the password.

   router> enable
   router% config terminal

   router(config)#crypto key generate rsa

   The name for the keys will be: netscape.mcom.com

   Choose the size of the key modulus in the range of 360 to 2048 for your
   General Purpose Keys. Choosing a key modulus greater than 512 may take a few
   minutes.

   How many bits in the modulus [512]:
   Generating RSA keys ...
   [OK]

   router(config)#crypto ca identity test-ca

   router(ca-identity)#enrollment url    http://ca-hostname.domain.com/cgi-bin/
                              pkiclient.exe

   router(ca-identity)#exit

   router(config)#crypto ca authenticate test-ca
   Certificate has the following attributes:
   Fingerprint: 24D34656 EB830C39 DD9E8179 0A4EBA98
   % Do you accept this certificate? [yes/no]: yes

   router(config)#crypto ca enroll test-ca

   %

   % Start certificate enrollment ..

   % Create a challenge password. You will need to verbally provide this
   password to the CA Administrator in order to revoke your certificate. For
   security reasons your password will not be saved in the configuration.
   Please make a note of it.

   Password:
   Re-enter password:

   % The subject name in the certificate will be: router.domain.com
   % Include the router serial number in the subject name? [yes/no]: yes
   % The serial number in the certificate will be: 08342063
   % Include an IP address in the subject name? [yes/no]: yes

   Interface: ethernet0

   Request certificate from CA? [yes/no]: yes
   % Certificate request sent to Certificate Authority
   % The certificate request fingerprint will be displayed.
   % The 'show crypto ca certificate' command will also show the fingerprint.

   router(config)# exit

   router#show crypto ca certificates

   CA Certificate
      Status: Available
      Certificate Serial Number: 1
      Key Usage: Not Set
   Certificate
      Subject Name
      Name: netscape.mcom.com
      IP Address: 208.12.63.193
      Serial Number: 08342063
      Status: Pending
      Key Usage: General Purpose
      Fingerprint: 91D70D7F D8BF0DFA E13F00B0 6EA706A0 00000000

Testing Your Enrollment Setup

This section provides a procedure for testing your enrollment setup in the legacy enrollment. If you want to do it through profiles, please read the instructions in Chapter 11 "Certificate Profiles." To test whether your end users can successfully enroll for a certificate using the authentication method you've set up:

  1. Go to the end-entity interface for the enrollment authority you configured.
    2. The default URL is as follows: https://<hostname>:<end_entity_HTTPS_port> or
    http://<hostname>:<end_entity_HTTP_port>
     
  2. In the Enrollment tab, open the enrollment form you customized.
  3. Fill in all the values and submit the request.
  4. The client prompts you to enter the password for your key database.
  5. When you enter the correct password, the client generates the key pair.
    6. Do not interrupt the key-generation process. Upon completion of the key generation, the request is submitted to the server for certificate issuance. The server subjects the request to the currently configured policy rules and issues the certificate only if the request passes all the policy rules.
     
    Upon receipt of a notification about the certificate issuance, install the certificate in your browser.
     
  6. Verify that the certificate is installed in the browser's certificate database; for example, in Communicator you can open the Security Info window and verify that the certificate is listed in there.
  7. If you've set up the directory- and PIN-based authentication with PIN removal, reenroll for another certificate using the same PIN. Your request should get rejected.
  8. If you've set up the portal enrollment, verify that an entry for the user is created in the directory. For example, you can point your browser to the portal directory and find out if an entry for the user for whom you requested the certificate exists.
    9. In the URL field, type
    ldap://<hostname>:<port>/<base_dn>??sub?(uid=<user_id>), substituting <hostname> with the fully qualified host name of the Directory Server, <port_number