Previous     Contents     Index     Next     
iPlanet Certificate Management System Plug-ins Guide



Chapter 1   Authentication Plug-in Modules


iPlanet Certificate Management System (CMS) provides a set of authentication plug-in modules that enable you to configure a Certificate Manager or Registration Manager to authenticate end users, based on specified criteria, when they enroll for a certificate. This chapter explains the authentication modules that are installed with the Certificate Manager and Registration Manager—it lists and briefly describes the modules and then explains each one in detail.

The chapter has the following sections:



Overview of Authentication Modules

Certificate Management System supports both manual and automated certificate issuance.

  • In the manual method of certificate issuance, end entities supply most of the information required by the server to formulate certificate requests and issue certificates. Manual issuance is also dependent on human agents; it requires that all end-entity certificate requests be approved by agents before the server can process the requests. To understand the role of an agent in your PKI, see section "Agents" in Chapter 13, Managing Privileged Users and Groups" of CMS Installation and Setup Guide.

  • In the automated method of certificate issuance, repositories, such as directories, supply part of the end-entity information. End entities only supply certain information—for example, a user ID and password—contained in the repository during certificate enrollment. The server uses this information for authenticating end entities before retrieving information required to formulate the certificate request from the repository.

For details on the manual method of certificate issuance, see "Manual Authentication". For the automated method of certificate issuance, Certificate Management System provides a set of plug-in modules. Plug-in modules are implemented as Java classes and are registered in the CMS authentication framework. The Authentication Plugin Registration tab of the CMS window (see Figure 1-1) lists all the modules and the corresponding classes that are currently registered with a CMS instance.

Figure 1-1    Default authentication modules for end-user enrollment


Table 1-1 lists the authentication modules provided for the Certificate Manager and Registration Manager; no authentication modules are provided for the Data Recovery Manager as it does not function as an enrollment authority in a PKI. You can use these modules to configure a Certificate Manager and Registration Manager to employ a specific authentication method during certificate enrollments.

Note that the name of the Java class for an authentication plug-in is in this format:

com.netscape.certsrv.authentication.<plugin_name>

where <plugin_name> is the name of a plug-in module. For example, the Java class for the UidPwdDirAuth module would be:

com.netscape.certsrv.authentication.UidPwdDirAuthentication


Table 1-1    Authentication plug-in modules for end user certificate enrollments  

Plug-in module name

Function

NISAuth  

Authenticates end users based on their user IDs and passwords stored in a NIS server. Optionally, uses an LDAP directory for formulating certificate subject names. For details, see "NISAuth Plug-in Module".  

PortalEnroll  

Authenticates online service users based on their user IDs and passwords stored in an LDAP directory. Also registers new users for the online service. For details, see "PortalEnroll Plug-in Module".  

UidPwdDirAuth  

Authenticates end users based on their user IDs and passwords stored in an LDAP directory. For details, see "UidPwdDirAuth Plug-in Module".  

UidPwdPinDirAuth  

Authenticates end users based on their user IDs, passwords, and PINs stored in an LDAP directory. For details, see "UidPwdPinDirAuth Plug-in Module".  

Because large corporations typically store corporatewide user, group, and network-resource data in LDAP-compliant directories, the default authentication modules provided for automated certificate enrollment use an LDAP directory for authenticating users or for formulating certificate subject names, or for both. If you already have an LDAP-compliant directory, such as Netscape Directory Server, with end-user data, you can use that directory for any of the purposes mentioned above. For example, if you have an NIS server and LDAP directory installations, you can use the NIS server for authenticating end users and the directory for formulating certificate subject names; end users will be required to provide only their NIS user IDs and passwords during enrollment.

If you don't have a directory deployed, you may use the Netscape Directory Server instance created at the time of CMS installation; in the documentation, this instance is identified as the Configuration Directory. For a demonstration on how to use this directory for issuing certificates to end users, see Chapter 3, "Default Demo Installation" of CMS Installation and Setup Guide.

If you determine that the default authentication modules do not meet your requirements, you can develop a custom authentication module using the CMS SDK, which is available in the form of Java Docs at this location:

<server_root>/cms_sdk/cms_jdk/javadocs

For general guidelines on developing custom authentication modules and adding them to the CMS authentication framework, check the tutorials on authentication. Be sure to take a look at the authentication-specific samples available at this location: <server_root>/cms_sdk/cms_jdk/samples/authentication

For instructions on how to configure a Certificate Manager and a Registration Manager to use one or more of the authentication methods, see section "Configuring Authentication for End-User Enrollment" in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

Keep in mind that in an automated certificate management setup, the Certificate Manager and Registration Manager use the configured authentication methods only during certificate enrollment. During certificate renewal, the servers rely on end users SSL client certificate for automated renewal. For automated revocation, the users can use their SSL-client certificate or a challenge password. For more information, see sections "Authentication for End Users During Certificate Renewal" and "Authentication for End Users During Certificate Revocation" in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

Certificate Management System also provides HTML forms-based interfaces for all the authentication methods it supports. Your end entities can use these forms for certificate enrollment. Explanation of each enrollment form, along with the corresponding authentication module, is covered in "Enrollment Forms". Certificate renewal and revocation forms are covered as a part of those processes. For details on individual form elements in the enrollment, renewal, and revocation forms, see the online help available by clicking the Help buttons on the HTML forms. You can also customize these forms to suit to your organization's requirements. For customization information, see CMS Customization Guide.



Manual Authentication


Manual authentication refers to operations which must be approved by a CMS agent, where no automated operation is possible. That is, a real person must log in to approve or reject request. By default, Certificate Management System provides manual-enrollment forms that enable you to request many types of certificates from the server. For details, see "Enrollment Forms".

Note that the manual authentication method is hardcoded; you cannot configure it in any other way. This ensures that when the server receives requests that lack authentication credentials, it sends those requests to the request queue for agent approval. It also means that if you don't configure a Certificate Manager or Registration Manager for any other authentication method, the server automatically sends all certificate-related requests to a queue where they await agent approval.

Figure 1-2 illustrates how the manual authentication method works during certificate enrollment.

Figure 1-2    Manual authentication of end entities during certificate enrollment

These are the steps shown in Figure 1-2:

  1. In the manual enrollment form, the end entity enters the information needed to request a certificate and submits the request to the server.

  2. When the server receives the request, it automatically lists the request in a certificate request queue for an agent to process.

  3. An agent verifies the authenticity of the request.

    • If the request is from a valid end entity, the agent verifies that all the information the end entity has provided in the request is correct, makes required modifications, if any, and approves the certificate request for issuance.

    • If the request is from an invalid end entity, the agent rejects the request, which in turn triggers a rejection notification to the end entity.

  4. When the server receives the agent-approved request, it subjects it to policy processing. For details, see Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

    • If the request fails any of the configured policies, the server rejects the request, logs an error message, and sends a rejection notification to the end entity.

    • If the request passes all the configured policies, the server issues the certificate.

    The certificate is delivered to the email address specified in the certificate request.



UidPwdDirAuth Plug-in Module

The UidPwdDirAuth plug-in module implements the directory-based authentication method. You can use this module for authenticating end users, provided their information is stored in an LDAP directory, during certificate enrollment.

Here's how the enrollment method works: as part of configuring a Certificate Manager and a Registration Manager, or both, for authentication, you specify an LDAP directory that the server must use to authenticate end users. End users enroll for a certificate by entering their user IDs and passwords for this authentication directory in an HTML form that is served by a Certificate Manager or Registration Manager (see "Enrollment Forms"). Once the server successfully authenticates an end user, it retrieves the rest of the information required to formulate the certificate from the directory.

Figure 1-3 illustrates how authentication based on a user ID and password works during certificate enrollment.

Figure 1-3    User ID- and password-based authentication of an end user

These are the steps shown in Figure 1-3:

  1. In the directory-based certificate enrollment form, the end user enters a user ID and password for the directory and submits the request to a Certificate Manager or Registration Manager.

  2. When the server receives the request, it looks up the directory that is configured for authenticating end users. The server verifies the authenticity of the user by checking the directory entries.

    • If the end user does not have a valid entry in the directory, the server rejects the request, logs an error message, and sends a rejection notification to the user.

    • If the end user has a valid entry in the directory, the server retrieves all the information required to construct the subject name for the user's certificate.

    If, for some reason, the directory to which the server binds for authenticating the user ID and password is unavailable, the server returns an LDAP error code and writes it to the log. When troubleshooting any authentication failures, if you see a log entry with an LDAP error code, check the corresponding error code at this URL: http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

    28/Jun/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101
    nentries=0 etime=0]

  3. Next, the server subjects the certificate request to policy processing. For details, see Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of UidPwdDirAuth

In the configuration file, the UidPwdDirAuth module is identified as auths.impl.UidPwdDirAuth.class=com.netscape.certsrv.
authentication.UidPwdDirAuthentication.

In the CMS window, the module is identified as UidPwdDirAuth. Figure 1-4 shows how configurable parameters of the module are displayed in the CMS window.

Figure 1-4    Parameters defined in the UidPwdDirAuth module


Table 1-2 gives details about each of these parameters and their values.


Table 1-2    Description of parameters defined in the UidPwdDirAuth module  

Parameter

Description

dnpattern  

Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

  • E = the first mail LDAP attribute value in the user's entry

  • CN = the (first) cn LDAP attribute value in the user's entry

  • OU = the second ou value in the user's entry DN

  • O = the (first) o value in the user's entry DN

  • C = the string US

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates, S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).  

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 Plug-in Module".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)  

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.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.  

ldap.ldapconn.host  

Specifies the host name of the authentication directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com  

ldap.ldapconn.port  

Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389  

ldap.ldapconn.
secureConn  

Specifies the type—SSL or non-SSL—of the port at which the authentication directory listens to requests from Certificate Management System.

  • Check the box if the port is an SSL (HTTPS) port. If your authentication directory is configured for SSL-enabled communication (with or without SSL client authentication), choose this option.

  • Leave the box unchecked if the port is a non-SSL (HTTP) port. If your authentication directory is configured for basic authentication, choose this option (default).

 

ldap.ldapconn.
version  

Specifies the LDAP protocol version.

Permissible values: 2 or 3.

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

Example: 3  

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 form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com  

ldap.minConns  

Specifies the minimum number of connections permitted to the authentication directory.

Permissible values: 1 to 3.

Example: 2  

ldap.maxConns  

Specifies the maximum number of connections permitted to the authentication directory.

Permissible values: 3 to 10.

Example: 8  



UidPwdPinDirAuth Plug-in Module


The UidPwdPinDirAuth plug-in module implements the directory- and PIN-based authentication method. You can use this module for authenticating users in the global LDAP domain during certificate enrollment. This authentication method is functionally very similar to the directory-based authentication explained in "UidPwdDirAuth Plug-in Module", except that for stronger authentication you combine a PIN or one-time password with the end users' user IDs and passwords.

Here's how the enrollment method works: as a part of setting up a Certificate Manager or a Registration Manager, or both for end-user authentication, you specify the LDAP directory that the server must use to authenticate end users. End users enroll for a certificate by entering their user IDs, passwords, and PINs in an HTML form that is served by the Certificate Manager or Registration Manager (see "Enrollment Forms"). Once the server successfully authenticates an end user, it retrieves the rest of the information required to formulate the certificate from the directory. You can also configure the server to either retain or remove the PIN from the directory following successful authentication.

Normally, user entries in directories do not contain PINs. In order to use the UidPwdPinDirAuth module, you must first populate the directory that you intend to use for authentication with unique PINs for users; each user to whom you intend to issue a certificate must know his or her PIN at the time of certificate enrollment, as he or she will be required to enter it in the enrollment form. To aid you in the process of generating unique PINs for users and adding them to the directory, Certificate Management System provides a command-line tool called the PIN Generator. For information about this tool, see CMS Command-Line Tools Guide.


Configuration Parameters of UidPwdPinDirAuth

In the configuration file, the UidPwdPinDirAuth module is identified as
auths.impl.UidPwdPinDirAuth.class=com.netscape.certsrv.
authentication.UidPwdPinDirAuthentication.

In the CMS window, the module is identified as UidPwdPinDirAuth. Figure 1-5 shows how configurable parameters of the module are displayed in the CMS window.

Figure 1-5    Parameters defined in the UidPwdPinDirAuth module


Table 1-3 gives details about each of these parameters.


Table 1-3    Description of parameters defined in the UidPwdPinDirAuth module  

Parameter

Description

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.

  • Check the box if you want the server to remove PINs from the directory after successful authentication. If you set the value to true, you must also specify the values for the ldap.ldapauth.bindDN and password parameters.

  • Uncheck the box if you want the server to leave PINs in the directory after authentication.

 

pinAttr  

Specifies the authentication directory attribute for PINs. If you used the PIN Generator utility (provided with Certificate Management System), the attribute is specified by the value of the objectclass parameter; the default value for this parameter is pin. For details, see section "Arguments" in Chapter 4, "PIN Generator Tool" of CMS Command-Line Tools Guide.

Permissible values: Any valid attribute name.

Example: pin  

dnpattern  

Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

  • E = the first mail LDAP attribute value in the user's entry

  • CN = the (first) cn LDAP attribute value in the user's entry

  • OU = the second ou value in the user's entry DN

  • O = the (first) o value in the user's entry DN

  • C = the string US

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,
S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).  

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 Plug-in Module".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)  

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.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.  

ldap.ldapconn.host  

Specifies the host name of the authentication directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com  

ldap.ldapconn.port  

Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389  

ldap.ldapconn.
secureConn  

Specifies the type—SSL or non-SSL—of the port at which the authentication directory listens to requests from Certificate Management System.

  • Check the box if the port is an SSL (HTTPS) port. If your authentication directory is configured for SSL-enabled communication (with or without SSL client authentication), choose this option.

  • Leave the box unchecked if the port is a non-SSL (HTTP) port. If your authentication directory is configured for basic authentication, choose this option (default).

 

ldap.ldapconn.
version  

Specifies the LDAP protocol version.

Permissible values: 2 or 3.

  • 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).

Example: 3  

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.

Permissible values: A valid bind DN.

Example: CN=pinmanager  

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 (see section "Required Start-up Information" in Chapter 8, "Starting and Stopping CMS Instances" of CMS Installation and Setup Guide.)

You need to specify this parameter only if you've selected removePin.  

ldap.ldapauth.
clientCertNickname  

Specifies the nickname or the friendly 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.)

Permissible values: Enter the name of a currently valid CMS certificate, for example, its SSL server certificate.

Example: Server-Cert  

ldap.ldapauth.
authtype  

Specifies the authentication type—basic authentication or SSL client authentication—required in order to remove PINs from the authentication directory.

Permissible values: BasicAuth or SslClientAuth.

  • BasicAuth specifies basic authentication. If you choose this option, be sure to enter the correct values for ldap.ldapauth.bindDN and password parameters; the server uses the DN from the ldap.ldapauth.bindDN attribute to bind to the directory (default).

  • SslClientAuth specifies SSL client authentication. If you choose this option, be sure to set the value of the ldap.ldapconn.secureConn parameter to true and the value of the ldap.ldapauth.clientCertNickname parameter to the nickname of the certificate to be used for SSL client authentication.

Example: BasicAuth  

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.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com  

ldap.minConns  

Specifies the minimum number of connections permitted to the authentication directory.

Permissible values: 1 to 3.

Example: 3  

ldap.maxConns  

Specifies the maximum number of connections permitted to the authentication directory.

Permissible values: 3 to 10.

Example: 9  



NISAuth Plug-in Module


The NISAuth module implements the NIS server-based authentication. You can use the module for authenticating unprivileged users in the NIS domain during certificate enrollment. The module enables you to deploy Public Key Infrastructure (PKI) leveraging an existing NIS server installation—it enables you to configure a Certificate Manager or Registration Manager to authenticate end users, based on their user IDs and passwords stored in an existing NIS server, and to issue certificates.

Optionally, you can configure the authentication module to do an LDAP correlation—that is, use the NIS directory to authenticate users based on the user ID and password they enter in the enrollment form, but compose certificate subject names from an LDAP-compliant directory, such as Netscape Directory Server. When using an LDAP directory to compose subject names, you can configure the module to search for and retrieve specific LDAP attribute values from the directory. The ability of the module to use an LDAP directory to form certificate subject names is useful in cases where the NIS server only stores user IDs and passwords and you don't want to formulate subject names using just common names and user IDs.

In the absence of an LDAP directory, subject names of all certificates issued by the server will be of the form CN=<FirstName LastName>,UID=<UserID>, where First Name and Last Name is a user's first and last names as specified in the NIS directory, and UserID is the user's NIS ID. To accommodate scenarios where the default subject-name form isn't adequate, the module supports a parameter named extendedDN. This parameter enables you to specify a suffix that the server should use for extending the default subject DN pattern.

Figure 1-6 illustrates how the NIS authentication module works during certificate enrollment.

Figure 1-6    NIS server-based authentication of an end user

These are the steps shown in Figure 1-6:

  1. In the NIS server-based certificate enrollment form, the end user enters his or her user ID and password for the NIS server and submits the request to a Certificate Manager or Registration Manager.

  2. When the server receives the request, it looks up the NIS server that is configured for authenticating end users. The server verifies the authenticity of the end user by checking the entries.

    • If the end user does not have a valid entry in the NIS server, the Certificate Manager or Registration Manager rejects the request, logs an error message, and sends a rejection notification to the user.

    • If the end user has a valid entry in the NIS server, the Certificate Manager or Registration Manager checks to see if any LDAP directory has been configured for retrieving attributes for constructing the certificate subject name. If a directory is specified, the server checks it for the user's entry, retrieves all the information required to construct the subject name, and adds the subject name to the certificate request. If a directory is unspecified, the server uses the NIS user's name, user ID, and extended DN (if specified) for the subject name.

    If, for some reason, the directory to which the server binds for retrieving user attributes is unavailable, the server writes the appropriate LDAP error code to the log. When checking the log for troubleshooting any authentication failures, if you see a log entry with an LDAP error code, check the corresponding error code at this URL: http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

    30/Dec/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101
    nentries=0 etime=0]

  3. Next, the server subjects the certificate request to policy processing. For details, see Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Configuration Parameters of NISAuth

In the configuration file, the NISAuth module is identified as
auths.impl.NISAuth.class=com.netscape.certsrv.authentication.
NISAuth.

In the CMS window, the module is identified as NISAuth. Figure 1-7 shows how configurable parameters of the module are displayed in the CMS window.

Figure 1-7    Parameters defined in the NISAuth module


Table 1-4 gives details about each of these parameters and their values.


Table 1-4    Description of parameters defined in the NISAuth module  

Parameter

Description

nisserver  

Specifies the NIS server name. (In Unix, use the ypwhich command to find the NIS server name.)

Permissible values: A valid server name.

Example: myServer  

nisdomain  

Specifies the NIS domain name. (In Unix, use the domainname command to find the domain name.)

Permissible values: A valid domain name.

Example: siroe.com  

dnpattern  

Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

  • E = the first mail LDAP attribute value in the user's entry

  • CN = the (first) cn LDAP attribute value in the user's entry

  • OU = the second ou value in the user's entry DN

  • O = the (first) o value in the user's entry DN

  • C = the string US

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,

S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).  

extendedDN  

Specifies the suffix that the server should use for extending the default subject DN when an LDAP directory for retrieving such information is not specified. The value you specify in this field is used by the sever to suffix the default subject name in certificates, which is in the form CN=<FirstName LastName>,UID=<UserID>.

Example: If you assign OU=People,O=siroe.org,C=US as the extended DN, subject names in certificates would be of this form:

CN=<FirstName LastName>,UID=<UserID>,OU=People,
O=siroe.org,C=US  

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 Plug-in Module".

Entering values for this parameter is optional.

Permissible values: Any valid LDAP string attributes, separated by commas.

Example: mail

(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)  

ldapByteAttributes  

Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end user. If specified, the values corresponding to these attributes will be copied from the LDAP 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.

Permissible values: Any valid LDAP byte attributes, separated by commas.

Example: jpegPhoto

This sample configuration specifies that the value of the LDAP attribute named jpegPhoto (which is included in the standard inetOrgPerson object class) should be stored in the authentication token and be used to put the user's picture in his or her certificate.  

ldap.ldapconn.host  

Specifies the host name of the LDAP directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: corpDirectory.siroe.com  

ldap.ldapconn.port  

Specifies the TCP/IP port at which the LDAP directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389  

ldap.ldapconn.
secureConn  

Specifies the type—SSL or non-SSL—of the port at which the LDAP directory listens to requests from Certificate Management System.

Permissible values: true or false.

  • true specifies that the port is an SSL (HTTPS) port. If your directory is configured for SSL-enabled communication (with or without SSL client authentication), choose this option.

  • false specifies that the port is a non-SSL (HTTP) port. If your directory is configured for basic authentication, choose this option.

Example: false  

ldap.ldapconn.
version  

Specifies the LDAP protocol version of the LDAP directory.

Permissible values: true or false.

  • 2 specifies LDAP version 2. If your 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.

Example: 3  

ldap.basedn  

Specifies the base DN for searching the LDAP directory—the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com  

ldap.minConns  

Specifies the minimum number of connections permitted to the LDAP directory.

Permissible values: 1 to 3

Example: 2  

ldap.maxConns  

Specifies the maximum number of connections permitted to the LDAP directory.

Permissible values: 3 to 10

Example: 10  



PortalEnroll Plug-in Module


The PortalEnroll module implements portal enrollment. This module enables you to issue certificates and create directory entries for users who do not yet have an entry in the directory. For example, if your company runs a portal service, such as Netscape NetcenterTM, you can use the PortalEnroll module to issue certificates to new users when they register for the online service. You can also use the module to authenticate and issue certificates to your extranet users. For example, if you have deployed extranets for partners and vendors, you can use the module to authenticate and issue certificates to these users when they register for the service.

The PortalEnroll module does following:

  • Performs dual operations, registration and authentication, eliminating the need for users to use separate forms to register for an online service and to request a certificate; the module enables deployment of certificates along with registration in an LDAP-compliant directory.

  • Verifies the uniqueness of the new user's chosen user name against an LDAP-compliant user directory and uses the user name as the only authentication token required to obtain a certificate.

  • Uses the information from the enrollment form to create new user entries and update directory entry attributes for unique usernames.

  • Leverages an existing LDAP-compliant user directory, typically used for storing user information.

There are many advantages in issuing certificates to your user community:

  • Certificates enable you to uniquely identify users and establish a relationship with users in that you can use their identities to track services and features utilized by these users and use this information to offer customized services to them—certificates become equivalent to the way online services utilize cookies for personalization.

  • Certificates also enable you to make your online service subscription based—because a certificate's life is tied to its validity period, by issuing certificates with specific validity period you can enforce users to subscribe to your online service by renewing their certificate before its expiry.

  • Certificates also enable you to remove people from your user base and add them back after giving them a credential—by making a certificate issued to a new user expire after a specific validity period you can restrict that user from using your service, and put the user back on service by forcing the user to renew the expired certificate after giving them a credential. For example, assume you have an extranet deployed for your partners. You have no prior knowledge of people who will register as your partners, but you want them to register and you want to trust the information they provide during registration. By issuing them a certificate with a short validity period you can limit them from using your service for that period. In the meantime, you can verify their registration data and decide whether to allow them to continue using your service; if you want them to be your partners, you allow them to renew their certificates before they expire; if you don't want them as your partners, you reject their certificate renewal requests.

    Note that Certificate Management System can send automated renewal notifications to users before their certificates expire; see "RenewalNotificationJob Plug-in Module".

Functionally, the portal authentication module is very similar to the directory-based authentication module (see "UidPwdDirAuth Plug-in Module") except that instead of binding to the directory as the enrolling user, Certificate Management System binds as some directory account with permission to create and update user entries. The server then queries the directory for the user name specified by the user and if it doesn't find a match, it adds the entry with all the standard LDAP field names that match the directory attributes.

For example, if the HTTP form input contains data such as surname, common name, and phone number, the corresponding LDAP attributes would be set in the directory; for details, see "Enrollment Forms". The server also uses a combination of these attributes (which you can specify using the dnpattern parameter defined in the module) to construct subject names for certificates.

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. For guidelines on how to customize the module, check the sample located here: <server_root>/cms_sdk/cms_jdk/samples/authentication

Figure 1-8 illustrates how the portal authentication module works during certificate enrollment.

Figure 1-8    Portal authentication of an end user

These are the steps shown in Figure 1-8:

  1. In the portal enrollment form, the end user enters registration information, such as a user name or ID, password, first name, last name, and mailing address, and submits the request to the server.

  2. When the server receives the request, it verifies that the required fields contain appropriate information, for example, the values entered in the Password and Confirm Password fields match. Next, the server looks up the directory that is configured for authenticating portal service users for a matching user name.

    • If the server finds a matching user name in the directory, it rejects the request, logs an error message, and sends a rejection notification to the end user.

    • If the server fails to find a matching user name in the directory, it uses the registration information to create a user entry for the new user and add relevant attributes. The server also retrieves information required to construct the subject name for the certificate.

    If, for some reason, the directory to which the server binds for authenticating the user ID and password is unavailable, the server returns an LDAP error code and writes it to the log. When troubleshooting any authentication failures, if you see a log entry with an LDAP error code, check the corresponding error code at this URL: http://help.netscape.com/kb/server/970303-9.html

    A sample log entry with an LDAP error code is shown below:

    28/Jun/1999:18:40:25 -0700] conn=0 op=7 RESULT err=32 tag=101
    nentries=0 etime=0]

  3. Next, the server subjects the certificate request to policy processing. For details, see Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.

    • If the request fails any of the configured policies, the server rejects the request, logs an error message, and sends a rejection notification to the end user. Note that if this happens, the user won't be able to reregister using the same user name.

    • If the request passes all the configured policies, the server issues the end user a certificate.

      The end user gets the certificate, which, if the server is configured to do so, is delivered to the email address specified in the request or in the directory; for information on configuring a Certificate Manager or Registration Manager to send automated notifications, see section "Notifications of Certificate Issuance to End Entities" in Chapter 16, "Setting Up Automated Notifications" of CMS Installation and Setup Guide.


Configuration Parameters of PortalAuth

In the configuration file, the PortalEnroll module is identified as
auths.impl.PortalEnroll.class=com.netscape.certsrv.
authentication.PortalEnroll.

In the CMS window, the module is identified as PortalEnroll. Figure 1-9 shows how configurable parameters for the module are displayed in the CMS window.

Figure 1-9    Parameters defined in the PortalEnroll module


Table 1-5 gives details about each of these parameters and their values.


Table 1-5    Description of parameters defined in the PortalEnroll module  

Parameter

Description

dnpattern  

Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.

Permissible values: Any valid DN string composed from standard DN attributes, which must be separated by commas; see "DNs in Certificate Management System".

The syntax is illustrated in the following example:

E=$attr.mail.1, CN=$attr.cn, OU=$dn.ou.2, O=$dn.o, C=US

This sample configuration specifies that the subject name should be formulated as follows:

  • E = the first mail LDAP attribute value in the user's entry

  • CN = the (first) cn LDAP attribute value in the user's entry

  • OU = the second ou value in the user's entry DN

  • O = the (first) o value in the user's entry DN

  • C = the string US

If this parameter value is empty or not set, the server uses E=$attr.mail, CN=$attr.cn, O=$dn.o, C=$dn.c as the DN pattern.

This default DN pattern works well with Netscape Communicator and other browsers. For Communicator, if you leave out E= in end-user certificates,
S/MIME may not work correctly (assuming lack of other extensions in the certificate). Also, if C= and O= are left out, certificate display looks strange in Communicator (when the Display Certificate button is clicked).  

ldap.ldapconn.host  

Specifies the host name of the portal directory.

Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.

Example: portalDirectory.siroe.com  

ldap.ldapconn.port  

Specifies the TCP/IP port at which the portal directory listens to requests from Certificate Management System.

Permissible values: Any valid port number.

Example: 389  

ldap.ldapconn.
secureConn  

Specifies the type—SSL or non-SSL—of the port at which the portal directory listens to requests from Certificate Management System.

  • Check the box if the port is an SSL (HTTPS) port. If your portal directory is configured for SSL-enabled communication (with or without SSL client authentication), choose this option.

  • Leave the box unchecked if the port is a non-SSL (HTTP) port. If your portal directory is configured for basic authentication, choose this option (default).

 

ldap.ldapconn.
version  

Specifies the LDAP protocol version.

Permissible values: 2 or 3.

  • 2 specifies LDAP version 2. If your portal 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).

Example: 3  

ldap.ldapauth.
bindDN  

Specifies the user account to bind as in order to create and update user entries in the portal directory. It is recommended that you create and use a separate user account that has permission to create user entries and modify user attributes in the directory. For example, don't use the directory manager's entry as it has privileges to modify the entire directory content.

Permissible values: A valid bind DN.

Example: CN=Portal Registration Manager  

password  

Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter.

Permissible values: As applicable.  

ldap.ldapauth.
clientCertNickname  

Specifies the nickname or the friendly name of the certificate to be used for SSL client authentication to the portal directory. Make sure that the certificate is valid and has been signed by a CA that is trusted in the portal directory's certificate database, and that the portal directory's certmap.conf file has been configured to correctly map the certificate to a DN in the directory.

Permissible values: Enter the name of a currently valid CMS certificate, for example, its SSL server certificate.

Example: Server-Cert  

ldap.ldapauth.
authtype  

Specifies the authentication type—basic authentication or SSL client authentication—required to communicate with the portal directory.

Permissible values: BasicAuth or SslClientAuth.

  • BasicAuth specifies basic authentication. If you choose this option, be sure to enter the correct values for ldap.ldapauth.bindDN and password parameters; the server uses the DN from the ldap.ldapauth.bindDN attribute to bind to the directory (default).

  • SslClientAuth specifies SSL client authentication. If you choose this option, be sure to set the value of the ldap.ldapconn.secureConn parameter to true and the value of the ldap.ldapauth.clientCertNickname parameter to the nickname of the certificate to be used for SSL client authentication.

Example: BasicAuth  

ldap.basedn  

Specifies the base DN for searching the portal directory—the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.

Permissible values: Any valid DN string of up to 255 characters.

Example: O=siroe.com  

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; see "Enrollment Forms".

Example: inetOrgPerson  

ldap.minConns  

Specifies the minimum number of connections permitted to the directory.

Permissible values: 1 to 3

Example: 2  

ldap.maxConns  

Specifies the maximum number of connections permitted to the directory.

Permissible values: 3 to 10

Example: 10  



Certificate-Based Enrollment


Certificate Management System supports certificate-based enrollment for browser certificates. End users can use preissued certificates to authenticate to the server in order to enroll for certificates. Below are two deployment scenarios that explain the usefulness of certificate-based enrollment.

  • You have deployed a client that can generate dual key pairs and you want to issue dual certificates (one for signing and another for encrypting data) to your users. You also want to make sure that users put their key materials only on hardware tokens.

    One way to achieve this would be to initialize hardware tokens in bulk and preload them with dual certificates issued by Certificate Management System for dual key pairs. You generate these certificates with some generic-looking common names, for example, hardwaretoken1234. This way, there's no one-to-one relation between users and the hardware tokens initially. Once the tokens are ready, you make them available to users by some means, for example, from a vending-machine-like box in the break room. Basically, a user can get and use any pre-initialized and certificate-loaded hardware token.

    Next, each user uses the randomly-picked token to enroll (strictly speaking, renew) for a pair of certificates that have a subject name derived from their LDAP attribute values; the certificates will be issued for the existing key pairs preloaded into the token, but now the key pairs will be associated with the user's identity.

  • You want users use the signing certificate already in their possession to get an encryption certificate.

    For example, assume you have deployed Certificate Management System and have issued single certificates (for single key pairs) to users. Recently, you deployed a client application (such as Netscape Personal Security Manager) that is capable of generating dual key pairs. Your CMS installation includes the Data Recovery Manager, but you weren't using it until now because you didn't have clients that were capable of generating dual-key pairs. Now, you want your users to use their signing certificates as authentication tokens to request another certificate that they'll use for encrypting data.

To enable you to configure Certificate Management System for certificate-based enrollment, the following three enrollment forms are provided:

  • CertBasedDualEnroll.html—this form enables end users to request dual certificates—one for signing another for encryption—by submitting pre-issued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate the user uses for authentication, uses the configured directory to formulate subject names for the new certificates, and issues the certificates.

  • CertBasedEncryptionEnroll.html—this form is provided as a sample. It enables end users to request encryption certificates by submitting pre-issued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate the user uses for authentication, uses the configured directory to formulate the subject name for the new certificate, and issues the certificate.

  • CertBasedSingleEnroll.html—this form is provided as a sample. It enables end users to request signing certificates by submitting pre-issued certificates as authentication tokens; when a user enrolls for a certificate, the server verifies the CA that has issued the certificate the user uses for authentication, uses the configured directory to formulate the subject name for the new certificate, and issues the certificate.

Note that all three enrollment forms by default work with the directory-based authentication module, named UidPwdDirAuth, explained in "UidPwdDirAuth Plug-in Module". You can use the certificate-based enrollment forms with any of the authentication modules, for example, directory- and PIN-based or NIS-server based authentication modules. However, this would require you to add the necessary hidden fields or variables to enrollment form that's provided for the corresponding authentication module; check Table 1-6 to figure out which enrollment form works with which module.

In general, the following three hidden variables distinguish certificate-based enrollment forms from other enrollment forms:

  • certauthEnroll—this variable specifies whether certificate-based enrollment is turned on or off.

  • certauthEnrollType—this variable specifies one of the three certificate-based-enrollment types: dual, single, or encryption; dual specifies that the enrollment request is for dual certificates; single specifies that the enrollment request is for a signing certificate; and encryption specifies that the enrollment request is for an encryption certificate.

    Note that choosing dual would require a client that's capable of generating dual key pairs.

  • doSslAuth—this variable specifies whether the server should request the client for SSL client authentication. You must set the value of this parameter to on and make sure that the port number specified in the authentication instance is an SSL port.

Before modifying a form, be sure to take a look at the default certificate-based enrollment forms. Also check the customization-related information for the enrollment forms in CMS Customization Guide.

In addition to the enrollment forms, a policy plug-in named IssuerConstraints is also provided; see "IssuerConstraints Plug-in Module". This plug-in allows you to configure the server to recognize the CA that issues the certificates that your users will use for authentication purposes; you need this policy to ensure that the CA issues certificates only to those users who present a valid certificate during enrollment. Note that in the current implementation, the CA that issues the new certificates must be the same as the one that issues the certificates users will use for authentication. That is, the issuer DN in the authentication certificate must match the issuer DN specified in the policy configuration.

Here are a few things to keep in mind:

  • Enrollment requests for dual certificates must be submitted directly to the Certificate Manager; the Registration Manager doesn't support generation of dual certificates.

  • The Certificate Manager provides a bulk-enrollment interface, which can be used to preload keys and certificates on hardware tokens before distributing them to users for certificate enrollment. For details, see section "Bulk Enrollment Interface" of CMS Customization Guide.

  • When using certificate-based enrollment, the IssuerConstraints policy must be enabled and configured to check the CA (its issuer DN) in certificates users will use to authenticate to the server. Also, the value assigned to the issuerDN parameter must match the issuer DN of the CA that was used to generate hardware tokens in bulk.

  • Enabling certificate-based enrollment creates one link, named Certificate, under the list of user-enrollment links in the end-entity enrollment interface. By default, the link points to the CertBasedDualEnroll.html form. If you want to use either of the other two forms, CertBasedEncryptionEnroll.html or CertBasedSingleEnroll.html, you should associate the Certificate link to the form you want to use or add more links to the index.html file.

General guidelines to set up certificate-based enrollment (for dual certificates) are as follows:

  • On the server side you need do the following:

    • Customize the enrollment form you want your users to use for enrollment.

    • Enable the appropriate enrollment option, such as directory-based enrollment or NIS-server based enrollment. Be sure to configure the authentication module to compose the desired DN pattern.

    • Enable the Key Usage extension policy explained in "KeyUsageExt Plug-in Module".

      Take a look at the key-usage policy rule named ClientCertKeyUsageExt and see if it needs any modifications. For example, to get a signing-only certificate, you need to turn off keyEncipherment and dataEncipherment bits of the extension; similarly, to get an encryption-only certificate, you may need to turn off the digitalSignature bit of the extension.

    • Configure the IssuerRule policy with the correct issuer DN and set the predicate expression so that the rule is applied to client certificates only.

  • On the client side, you need to do the following:

    • Install drivers for the hardware tokens you want to use during bulk generation of key pairs and corresponding certificates with generic subject names.

    • If you want to issue dual certificates, install a client that can generate dual key pairs; for example, Netscape Communicator (version 4.7 or later) with Netscape Personal Security Manager.



Enrollment Forms

The end-entity interface of the Certificate Manager and the Registration Manager include default HTML forms for all the authentication methods—manual and automated—supported by the server.

Enrollment forms can be categorized into two types, depending on the authentication method they support.

  • Manual enrollment forms—these forms work with the built-in manual authentication module (see "Manual Authentication"), enabling users to request all types of certificates such as client certificates, server certificates, object-signing certificates, CA certificates, and so on. Manual enrollment for end users requires them to enter information such as name, email ID, department, organization, and the state and the country in which the organization is located, and submit the request for a personal certificate. Manual enrollment for server certificates requires the server administrator to paste the certificate signing request (in the PKCS#10 format) from the server into the specified area in the enrollment form; see Chapter 24, "Issuing and Managing Server Certificates" of CMS Installation and Setup Guide.

    Because the Certificate Manager or Registration Manager cannot verify the information an end user or administrator enters against anything, it builds the certificate request based on the user input and puts the request in the agent queue for approval.

  • Automated enrollment forms—these forms work with the corresponding plug-in module, enabling users to request certificates by authenticating to the configured repository, for example an LDAP directory or NIS directory.

All enrollment forms are accessible from the Enrollment tab of the End Entity Services interface. Note that by default the Enrollment tab lists only those forms that are associated with the manual enrollment method (it does not list the forms provided for the automated-enrollment methods). However, when you create an instance of any of the authentication modules provided for automated end-user enrollment—for example, directory-based or NIS-server based authentication—a link to the corresponding form is automatically created under the Browser section of the Enrollment tab. Instructions for enabling automated end-user enrollments is covered in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

Before asking users to use any of the enrollment forms, you should review the form and make the appropriate changes to the form content. For example, some of the forms include instructions for administrators and you should delete those lines. Files for all enrollment forms are located here:

<server_root>/cert-<instance_id>/web/ee

For basic instructions to customize any of the enrollment forms, see section "Step 5. Set Up the Enrollment Interface" in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

For advanced information on customizing the HTML forms, including how to make changes to the embedded Javascript functions, see CMS Customization Guide.

Figure 1-10 shows the End Entity Services interface of a Certificate Manager with the manual enrollment form for end users selected.

Figure 1-10    End Entity Services interface of a Certificate Manager


Table 1-6 lists the forms that correspond to the menu options in the Enrollment tab of the End Entity Services interface of the Certificate Manager and Registration Manager.


Table 1-6    Default forms for end-entity enrollment  

Menu link and form filename

Description

Browser (This section lists menu options for end-user enrollments.)

Manual
(ManUserEnroll.html)  

End users can use this form to request SSL client and S/MIME certificates. Requests submitted using this form get queued for agent approval.  

Directory
(DirUserEnroll.html)  

This form works with the UidPwdDirAuth module, enabling end users to request SSL client and S/MIME certificates by entering their user IDs and passwords for the directory; the server verifies this information against the configured directory and issues the certificate.  

Directory and PIN
(DirPinUserEnroll.html)  

This form works with the UidPwdPinDirAuth module, enabling end users to request SSL client and S/MIME certificates by entering their user IDs, passwords, and PINs for the configured directory; the server verifies this information against the specified directory and issues the certificate.  

NIS
(NISUserEnroll.html)  

This form works with the NISAuth module, enabling end users to request SSL client and S/MIME certificates by entering their NIS user IDs and passwords for the configured NIS server.  

Portal
(PortalEnrollment.html)  

This form works with the PortalEnroll module, enabling end users to register for an online service and at the same time submit a request for a personal certificate. Note that the form models the standard LDAP object class inetOrgPerson, which has many useful attributes that can be used in a real portal deployment.

As a part of registration, a user is required (by the portal authentication module) to supply a user ID and password for user ID validation and a first and last name for user registration. Entering information in other fields are optional; the server retrieves the rest of the information needed to construct the subject name for the certificate from the directory. As explained in "PortalEnroll Plug-in Module", if the user ID is unique, the server issues a certificate and registers the user automatically. To protect the privacy of a user's password, the server turns it in to a SHA-1 or MD5 hashed password before storing it in the directory.  

Certificate
(CertBasedDualEnroll.html)  

This form by default works with the UidPwdDirAuth module, enabling end users to request dual certificates (one for signing another for encryption) by submitting pre-issued certificates as authentication tokens; the server verifies the CA that has issued the certificate, uses the configured directory to formulate the subject names for the new certificates, and issues the certificate.

Note that the link appears only if you create an instance of the UidPwdDirAuth module and if the port number specified in the instance configuration is an SSL port. For details, see "Certificate-Based Enrollment".  

Server (This section lists menu options for SSL server, Registration Manager, Certificate Manager, and OCSP Responder enrollments.)

SSL Server
(ManServerEnroll.html)  

Server administrators can use this form to request SSL server certificates for SSL-enabled servers, such as Netscape Administration Server and Directory Server. Requests submitted using this form get queued for agent approval.  

Registration Manager
(ManRAEnroll.html)  

Registration Manager administrators can use this form to request a signing certificate for a Registration Manager; see section "Signing Key Pair and Certificate" in Chapter 14, "Managing CMS Keys and Certificates" of CMS Installation and Setup Guide. Requests submitted using this form get queued for agent approval.  

Certificate Manager
(ManCAEnroll.html)  

Certificate Manager administrators can use this form to request CA signing certificates for Certificate Managers functioning as subordinate CAs; see section "CA Signing Key Pair and Certificate" in Chapter 14, "Managing CMS Keys and Certificates" of CMS Installation and Setup Guide. Requests submitted using this form get queued for agent approval.

Only the Certificate Manager provides this form.  

OCSP Responder
(OCSPResponder.html)  

Server administrators can use this form to enroll for an OCSP responder certificate. Requests submitted using this form get queued for agent approval.  

WTLS (This section lists menu options for wireless certificate enrollments, and the section appears only if you configured the Certificate Manager to support issuance of Wireless Transport Layer Support (wTLS)-compliant certificates during installation.)

Client
(WTLSManUserEnroll.html)  

Users can use this form to enroll for a wireless certificate.

Only the Certificate Manager provides this form.  

Server
(WTLSManServerEnroll.html)  

Server administrators can use this form to enroll for a wireless certificate; the certificate request can be in PKCS#10 format.

Only the Certificate Manager provides this form.  

Other (This section lists menu options for object signing enrollments.)

ObjectSigning (PKCS10)
(ObjSignPKCS10Enroll.html)  

Server administrators can use this form to enroll for a certificate (by submitting the request in the PKCS #10 format) that allows them to sign objects, such as Java applets. Requests submitted using this form get queued for agent approval.  

ObjectSigning (Browser)
(ManObjSignEnroll.html)  

End users and administrators can use this form to enroll for a certificate that allows them to sign objects, such as Java applets. Requests submitted using this form get queued for agent approval.

Note that when issuing an object signing certificate to Microsoft IE, if you need to generate a .CER and a .PVK file for use by Microsoft signcode tool, follow the instructions in "Generating Files Required By Third-Party Object Signing Tools".  

CMC
(CMCResponder.html)  

End users and administrators can use this form to submit a certificate request in the CMC format.  


Customizing Enrollment Forms for Generating DSA Key Pairs

Netscape Communicator (version 4.x and later) can successfully obtain and use DSA client certificates for SSL client authentication. These versions of Communicator can also recognize the signature on SSL certificates signed by a DSA CA. In order for Communicator to generate a DSA key pair, you must modify the KEYGEN tag in the default certificate enrollment forms; the modifications will indicate that the DSA algorithm is to be used, and will also supply the PQG parameters. For details on the KEYGEN tag, see the document entitled Netscape Extensions for User Key Generation available at this site:

http://home.netscape.com/eng/security/comm4-keygen.html

Depending on the enrollment plug-in you want to use for authenticating end users, you may need to modify the KEYGEN tags in the following certificate enrollment forms:

  • DirPinUserEnroll.html

  • DirUserEnroll.html

  • ManObjSignEnroll.html

  • ManUserEnroll.html

  • NISUserEnroll.html

  • PortalEnrollment.html

These files are located in this directory: <server_root>/cert-<instance_id>/web/ee

The procedure below explains how to modify an enrollment form to generate a DSA key pair when used with Netscape Communicator:

  1. Go to the configuration directory of the Certificate Manager: <server_root>/cert-<instance_id>/config

  2. Open the Certificate Manager's configuration file (CMS.cfg) in a text editor.

  3. Open the enrollment form in a text editor.

  4. In the configuration file, find the DSSParms entry; this entry represents the PQG attribute and its value contains the PQG parameters that the CA has generated during configuration.

  5. Copy the value of the DSSParms entry.

  6. Go to the text editor that has the enrollment form open.

  7. Search for the KEYGEN tag.

  8. Insert the cursor at the end of the word KEYGEN, add a space after the word KEYGEN, and type the following:

    keytype="DSA" PQG=

  9. Paste the value of the DSSParms entry following the equal to (=) sign and enclose the value you pasted in double quotes (" ").

    An example of a modified KEYGEN tag is shown below (the modifications are shown in bold):

    <KEYGEN keytype="DSA"
    PQG="MIIBHgKBgQCsQeVqw5ID/xhSe7s4vLaOuKskCFJN23OBgWCEquYIZbMZdHN7015p
    6nN7XsDpTWBccLdrSdpMxmJd8rF2agb3tbk9hjZ6//MfLCTAwvegdgAzzRwB7akOgYD/SpPFb
    7rYuvPfkiRjiDDrrp9r+csWqnue9uABvJtWGnW8WVYP6wIVAMCRu0u3q+PORrJxO9Qcswzr
    LpnfAoGAM3ZBjxLTPbXOgWIXHZnIFSpGAW1JzK5ywEtnabJWfiIRrWi3hyWLj98PcIc2cxbp
    Oh60rwqeElUMv74V72Q2+HwIQwsPvTFyQUcBtOG40zlXoFwEqlaqDoXv3iA0Zp2XQy/JQFbx
    23J+0HKz7iB7co04LCa0wDU7Z0x+oTwmsd0=    " name="subjectKeyGenInfo">

  10. Repeat steps 7 through 9 to modify any additional KEYGEN tags.

  11. Save your changes.

  12. Next, configure the Certificate Manager to accept DSA key based certificate enrollment requests.

    A Certificate Manager by default only accepts RSA key-based requests. For the server to accept DSA key based certificate requests, the value of the algorithms parameter in the KeyAlgRule policy rule must be set to RSA,DSA. For instructions to change policy rules, see Chapter 18, "Setting Up Policies" of CMS Installation and Setup Guide.


Generating Files Required By Third-Party Object Signing Tools

When issuing an object-signing certificate to Microsoft IE, Certificate Management System can generate a certificate (.CER) and a private key (.PVK) files for use by Microsoft signcode tool or any third-party sign tools that rely on these files. For the server to generate these files, you must edit the default form provided for requesting an object-signing certificate for browsers.

To generate the private-key file:

  1. Go to this directory: <server_root>/cert-<instance_id>/web/ee

  2. Locate the file named ManObjSignEnroll.html.

  3. Open it in an editor.

  4. Search for this line:

    Enroll.GenKeyFlags = 1 ' key exportable

  5. Type the following line below it:

    Enroll.PVKFilename = "<pvk_file_path>"

    Your changes should look like this:

    ...
    Enroll.GenKeyFlags = 1 ' key exportable
    Enroll.PVKFilename = "<pvk_file_path>"
    szCertReq = Enroll.createPKCS10(szName, "1.3.6.1.5.5.7.3.2")
    ...

  6. Replace <pvk_file_path> with the absolute path, including the filename, to the directory in which you want the private key file created; for example, "C:\myKey.PVK". Be sure to use the .PVK extension and to enclose the path in double quotes.

  7. Optionally, you may further edit the form to include a text field for entering the file path.

  8. Save your changes.

  9. Now use the form to issue an object-signing certificate.

If your users need to generate Software Publishing File (SPC) files for their object-signing certificates, you should ask them to use the Microsoft tool named cert2spc. The SPC file enables them to execute commands such as this:

signcode -spc myCert.spc -v myKey.pvk file.exe

Here's how a user can create a SPC file for an object-signing certificate:

  1. Open a web browser window.

  2. Go to the End Entity Services interface.

  3. Locate the object-signing certificate for which you want to create the SPC file.

  4. Scroll down the page (that shows the certificate information in detail) to find the certificate in base-64 encoded format. It looks like this:

    -----BEGIN CERTIFICATE-----

    MIICJzCCAZCgAwIBAgIBAzANBgkqhkiG9w0BAQQFADBCMSAwHgYDVQQKExdOZXRzY2FwZSBD
    b21tdW5pY2F0aW9uczngjhnMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4XDTk4MDgyNzE5MDw
    MFoXDTk5MDIyMzE5MDAwMnbjdgngYoxIDAeBgNVBAoTF05ldHNjYXBlIENvbW11bmljYXRpb
    25zMQ8wDQYDVQQLEwZQZW9wbGUxFzAVBgoJkiaJkIsZAEBEwdzdXByaXlhMRcwFQYDVQQDw5
    TdXByaXlhIFNoZXR0eTEjMCEGCSqGSIb3DbndgJA

    -----END CERTIFICATE-----

  5. Create an ASCII file named cert.b64.

  6. Copy and paste the base-64 encoded certificate blob, including the marker lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the file.

  7. Convert the text-based certificate to its DER-encoded format using the ASCII to Binary tool, explained in CMS Command-Line Tools Guide.

    For example, the command

    <server_root>/bin/cert/tools/AtoB cert.b64 cert.der

    converts the base-64 encoded certificate in the cert.b64 file to its DER-encoded format and writes the DER-encoded certificate to a file named cert.der.

  8. Next, use the Microsoft tool named cert2spc to convert the DER-encoded certificate to SPC format. For example, the command

    cert2spc cert.der cert.spc

    converts the DER-encoded certificate in the cert.der file to its SPC format and writes the certificate to a file named cert.spc.

For additional information, check these links:


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated April 02, 2001