Previous Contents Index Next |
iPlanet Certificate Management System Plug-ins Guide |
Chapter 1 Authentication Plug-in Modules
iPlanet Certificate Management Server (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 Managerit lists and briefly describes the modules and then explains each one in detail.
The chapter has the following sections:
Overview of Authentication Modules
UidPwdPinDirAuth Plug-in Module
PortalEnroll Plug-in Module SSOAuthentication Plug-In Module (page 52)
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 informationfor example, a user ID and passwordcontained 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.iplanet.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.iplanet.certsrv.authentication.UidPwdDirAuthentication
Table 1-1    Authentication plug-in modules for end user certificate enrollments
Plug-in module name
Function
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.
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.
Authenticates end users based on their user IDs and passwords stored in an LDAP directory. For details, see UidPwdDirAuth Plug-in Module.
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 iPlanet 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 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:
In the manual enrollment form, the end entity enters the information needed to request a certificate and submits the request to the server.
When the server receives the request, it automatically lists the request in a certificate request queue for an agent to process.
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.
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 .
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:
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.
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. 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]
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 entity.
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 UidPwdDirAuth
In the configuration file, the UidPwdDirAuth module is identified as auths.impl.UidPwdDirAuth.class=com.iplanet.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
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
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).
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 tokenthat 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.
(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)
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 modulesthat 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.
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.
Specifies the host name of the authentication directory.
Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.
Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.
Specifies the typeSSL or non-SSLof 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).
Specifies the base DN for searching the authentication directorythe 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.
Specifies the minimum number of connections permitted to the authentication directory.
Specifies the maximum number of connections permitted to the authentication directory.
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.iplanet.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
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.
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 .
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
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).
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 tokenthat 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.
(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)
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 modulesthat 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.
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.
Specifies the host name of the authentication directory.
Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.
Specifies the TCP/IP port at which the authentication directory listens to requests from Certificate Management System.
Specifies the typeSSL or non-SSLof 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).
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.
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.
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.
Specifies the authentication typebasic authentication or SSL client authenticationrequired 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.
Specifies the base DN for searching the authentication directorythe 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.
Specifies the minimum number of connections permitted to the authentication directory.
Specifies the maximum number of connections permitted to the authentication directory.
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 installationit 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 correlationthat 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 iPlanet 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:
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.
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. 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]
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.
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 NISAuth
In the configuration file, the NISAuth module is identified as
auths.impl.NISAuth.class=com.iplanet.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
Specifies the NIS server name. (In Unix, use the ypwhich command to find the NIS server name.)
Specifies the NIS domain name. (In Unix, use the domainname command to find the domain name.)
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
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).
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
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 tokenthat 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.
(This sample configuration specifies that the value of the mail attribute should be stored in the authentication token.)
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 modulesthat 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.
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.
Specifies the host name of the LDAP directory.
Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.
Specifies the TCP/IP port at which the LDAP directory listens to requests from Certificate Management System.
Specifies the typeSSL or non-SSLof 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.
Specifies the LDAP protocol version of the LDAP directory.
Specifies the base DN for searching the LDAP directorythe 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.
Specifies the minimum number of connections permitted to the LDAP directory.
Specifies the maximum number of connections permitted to the LDAP directory.
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 mysun.sun.com, 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 themcertificates become equivalent to the way online services utilize cookies for personalization.
Certificates also enable you to make your online service subscription basedbecause 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 credentialby 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 iPlanet 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:
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.
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. 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]
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.iplanet.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
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
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).
Specifies the host name of the portal directory.
Permissible values: The name must be in the <machine_name>.<your_domain>.<domain> form.
Specifies the TCP/IP port at which the portal directory listens to requests from Certificate Management System.
Specifies the typeSSL or non-SSLof 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).
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.
Specifies the password associated with the DN specified by the ldap.ldapauthbindDN parameter.
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.
Specifies the authentication typebasic authentication or SSL client authenticationrequired 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.
Specifies the base DN for searching the portal directorythe 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.
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.
Specifies the minimum number of connections permitted to the directory.
Specifies the maximum number of connections permitted to the directory.
SSOAuthentication Plug-In Module
CMS provides a Single Sign-On (SSO) authentication module for user authentication. The SunTM ONE Identity Server 6.0 will be integrated with the Certificate Server SSO authentication mechanism. This integration will make it possible for an Identity Server user to authenticate himself to the Certificate Server by providing his Single Sign-On token instead of userID and password. The user can also apply for a general-purpose user certificate with a single click of a button, eliminating the need to manually import or install the certificate. The user clicks the GetMyCert button in the Identity Server user profile page to automatically generate the user certificate.
The following section provides instructions for configuring the Certificate Server Single Sign-On (SSO) Authentication module to work with Identity Server 6.0.
Configuring SSOAuthenication
Enabling this feature is a three-part procedure. Part 1 is described in detail in this document. For details on Parts 2 and 3, please see the Identity Server 6.0 documentation when it becomes available.
Create an instance of SSOBasedAuthentication in CMS.
In Identity Server, configure the Security service to work in non-SSL Certificate Server enrollment.
In Identity Server, configure the Security service to work in non-SSL Certificate Server enrollment.
Create an instance of SSOBasedAuthentication in CMS.
In the Certificate Server window, click Configuration>Authentication>Add.
In the Select Authentication Plug-in Implementation window, select SSOBasedAuthentication, and then click Next.
In the Authentication Instance Editor, provide the following information:
com.iplanet.am.naming.url. This is the Universal Resource Identifier (URI) for the Identity Server Naming Service. Type a URL to be used in place of the default URI. Use the following form:
http://Identity_Server_root:portNumber/amserver/namingservice
password. Type the Shared Secret used by the Identity Server.
com.iplanet.am.cookie.name. Type the Cookie property used by Identity Server. The default is iplanetDirectoryPro.
com.iplanet.am.pcookie.name. Type the PCookie property used by Identity Server. The default is DProPcookie.
com.iplanet.am.services.deploymentDescriptor. Type the Deployment Descriptor property used by Identity Server. The default value is amserver.
Click OK.
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.htmlthis form enables end users to request dual certificatesone for signing another for encryptionby 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.htmlthis 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.htmlthis 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:
certauthEnrollthis variable specifies whether certificate-based enrollment is turned on or off.
certauthEnrollTypethis 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.
doSslAuththis 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 methodsmanual and automatedsupported by the server.
Enrollment forms can be categorized into two types, depending on the authentication method they support.
Manual enrollment formsthese 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 formsthese 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 enrollmentfor example, directory-based or NIS-server based authenticationa 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.)
End users can use this form to request SSL client and S/MIME certificates. Requests submitted using this form get queued for agent approval.
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.
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.
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.
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.
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.)
Server administrators can use this form to request SSL server certificates for SSL-enabled servers, such as iPlanet Administration Server and Directory Server. Requests submitted using this form get queued for agent approval.
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 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.
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.)
Users can use this form to enroll for a wireless certificate.
Server administrators can use this form to enroll for a wireless certificate; the certificate request can be in PKCS#10 format.
Other (This section lists menu options for object signing enrollments.)
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.
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.
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:
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:
Go to the configuration directory of the Certificate Manager: <server_root>/cert-<instance_id>/config
Open the Certificate Manager's configuration file (CMS.cfg) in a text editor.
Open the enrollment form in a text editor.
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.
Copy the value of the DSSParms entry.
Go to the text editor that has the enrollment form open.
Insert the cursor at the end of the word KEYGEN, add a space after the word KEYGEN, and type the following:
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/xhSe7s4vLaOuKskCFJN23OBgWCEquYIZbMZdHN
7015p6nN7XsDpTWBccLdrSdpMxmJd8rF2agb3tbk9hjZ6//MfLCTAwvegdgAzzRw
B7akOgYD/SpPFb7rYuvPfkiRjiDDrrp9r+csWqnue9uABvJtWGnW8WVYP6wIVAMC
Ru0u3q+PORrJxO9QcswzrLpnfAoGAM3ZBjxLTPbXOgWIXHZnIFSpGAW1JzK5ywEt
nabJWfiIRrWi3hyWLj98PcIc2cxbpOh60rwqeElUMv74V72Q2+HwIQwsPvTFyQUc
BtOG40zlXoFwEqlaqDoXv3iA0Zp2XQy/JQFbx23J+0HKz7iB7co04LCa0wDU7Z0x
+oTwmsd0=" name="subjectKeyGenInfo">
Repeat steps 7 through 9 to modify any additional KEYGEN tags.
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:
Go to this directory: <server_root>/cert-<instance_id>/web/ee
Locate the file named ManObjSignEnroll.html.
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")
...
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.
Optionally, you may further edit the form to include a text field for entering the file path. 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:
Open a web browser window.
Go to the End Entity Services interface.
Locate the object-signing certificate for which you want to create the SPC file.
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-----
MIICJzCCAZCgAwIBAgIBAzANBgkqhkiG9w0BAQQFADBCMSAwHgYDVQQKExdOZXRz
Y2FwZSBDb21tdW5pY2F0aW9uczngjhnMVQ2VydGlmaWNhdGUgQXV0aG9yaXR5MB4
XDTk4MDgyNzE5MDwMFoXDTk5MDIyMzE5MDAwMnbjdgngYoxIDAeBgNVBAoTF05ld
HNjYXBlIENvbW11bmljYXRpb25zMQ8wDQYDVQQLEwZQZW9wbGUxFzAVBgoJkiaJk
IsZAEBEwdzdXByaXlhMRcwFQYDVQQDw5TdXByaXlhIFNoZXR0eTEjMCEGCSqGSIb
3DbndgJA
-----END CERTIFICATE-----
Create an ASCII file named cert.b64.
Copy and paste the base-64 encoded certificate blob, including the marker lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- to the file.
Convert the text-based certificate to its DER-encoded format using the ASCII to Binary tool, explained in CMS Customization 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.
Next, use the Microsoft tool named cert2spc to convert the DER-encoded certificate to SPC format. For example, the command
For additional information, check these links:
http://www.lantimes.com/ltparts/connect/shoptalk1.htm
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated October 07, 2002