Examining the pkitmpl.xml file

The PKI Services XML template, pkitmpl.xml, defines:

A root CA URL.
The root CA URL is the URL of the PKI Services CA certificate.
The PKI Services ActiveX install URL for Windows XP and earlier versions of Windows.
This URL is the URL of the Windows installer program that installs the PKI Services ActiveX control on Microsoft Windows XP and earlier versions of Windows.
The PKI Services ActiveX install URL for Windows Vista and later versions of Windows.
This URL is the URL of the Windows installer program that installs the PKI Services ActiveX control on Microsoft Windows Vista and later versions of Windows.
One or more applications.
An application is a grouping of certificate request templates. This grouping might be done because the templates are shared among a set of end users or because the templates have a common administrator. A PKI Services installation can have one or more applications defined.
One or more certificate request templates.
A certificate request template is a predefined set of characteristics for certificate requests and the resulting certificates. Each certificate request template defines:
- The type of certificate request (for example, browser or server, SCEP preregistration request, SAF or PKI certificate)
- A name for the certificate request template, which is displayed to both the end user and the administrator
- A nickname (maximum of 8 characters) that uniquely identifies each template, which PKI Services uses to retrieve information about the template
- The values you want a user to input and whether those values are optional or required
- The values you want to supply for the user
- The values an administrator is allowed to supply
- Whether the certificate is automatically approved
- Whether the certificate is automatically renewed
- A set of preregistration rules (applicable only to SCEP preregistration requests), which define whether approval is needed based on the level of authentication provided

The XML template file, pkitmpl.xml, begins by defining the URL of the PKI Services CA certificate.

<tns:CA_cert_URL>/PKIServ/cacerts/cacert.der</tns:CA_cert_URL>

The CA_cert_URL is the URL of the PKI Services CA certificate. The URL can be relative to the PKIServ Web root context or absolute. This URL is displayed as a link with the text "Install the CA certificate to enable SSL sessions for PKI Services" on the home page for both end users and administrators. Users need to install the PKI Services CA certificate in order to use a secure connection and retrieve certificates.

Next pkitmpl.xmldefines the PKI Services ActiveX install URLs.

<tns:XEnroll_install_URL>http://hostname:port/PKIServ/PKIXEnroll/PKIXEnrollDeploy.msi<tns:XEnroll_install_URL>
<tns:CEnroll_install_URL>http://hostname:port/PKIServ/PKICEnroll/PKICEnrollDeploy.msi<tns:CEnroll_install_URL>

The tag for XEnroll_install_URL specifies the URL of the PKI Services ActiveX control installer program for Windows XP and earlier versions of Windows. The tag for CEnroll_install_URL specifies the URL of the PKI Services ActiveX control installer program for Windows Vista and later versions of Windows. Each URL can be relative to the PKI Services Web root context or absolute. The text "Install the PKI ActiveX Control to renew certificates" on the PKI Services home page for end users (see Figure 1) links to the URL specified for the version of Microsoft Windows running on the system. Users need to install the PKI Services ActiveX control to install renewed certificates using the Internet Explorer browser.

The application tag (<tns:application>) defines a particular set of end users. The application tag consists of an application name (in this case Customers) and one or more application templates (<tns:appltemplate>).

<tns:applname>Customers</tns:applname>
<tns:appltemplate>1-Year PKI SSL Browser Certificate</tns:appltemplate>

The contents of the appltemplate tag ("1-Year PKI SSL Browser Certificate", for example) corresponds to the certname element of a certreq_template tag.

A certificate request template is defined by a certreq_template tag, shown in Figure 1.

Figure 1. A certreq_template tag

<tns:certreq_template>
     <tns:certname>1-Year PKI SSL Browser Certificate </tns:certname>
     <tns:certtype>PKI Browser Certificate</tns:certtype>
     <tns:certtype_description>PKI Browser Certificate for Secured Connections</tns:certtype_description>
     ⋮

The certificate type tag (<tns:certtype>) can have one of the following values:

PKI Preregistration (for SCEP preregistration requests)
PKI Browser Certificate
PKI Server Certificate
PKI Key Certificate (for a certificate for which PKI Services has generated the key pair)
SAF Browser Certificate
SAF Server Certificate

The certificate type description (<tns:certtype_description>) is an optional tag. Its contents are used on the Web pages wherever the certificate type is to be displayed. This tag allows administrators to use words that they feel might be more understandable to their end users than the pre-defined values for the certificate types. A common use of this tag might be to translate the certificate types to another language. If this tag is omitted the contents of the certificate type tag (<tns:certtype>) is used as the certificate type description.

The request authentication type tag (<tns:request_authtype>) and retrieve authentication type tag (<tns:retrieve_authtype>) >) define the type of authentication that must be used to request or retrieve a certificate. The acceptable values for these tags are:

noAuthRunAsSurrogate: No authentication should be used. The task runs as a surrogate user.
zAuthRunAsSurrogate: The user will be prompted to authenticate (log in) to z/OS® using a RACF® user ID and password. The task runs as a surrogate user.
zAuthRunAsClient: The user will be prompted to authenticate (log in) to z/OS using a RACF user ID and password. The task runs as the client.

The next element of a certificate request template is the Auto-Approve indicator <tns:AutoApprove>). A value of Y or y indicates that any certificate requests made with this template should be automatically approved (no administrator approval is required and the administrator will not have an opportunity to modify or reject certificate requests). A value of N or n indicates that certificate requests made with this template are not automatically approved and must be approved by an administrator.

The next element of a certificate request template is the Auto-Renew indicator (<tns:AutoRenew>). A value of Y or y indicates that any certificate created using this template will be automatically renewed. A value of N or n indicates that certificates created using this template are not automatically renewed.

The following form fields are defined with tags in the certificate request template:

AltDomain
AltEmail
AltIPAddr
AltOther
AltURI
BusinessCat
ClientName
CommonName
Country
CustomExt
DomainName
DNQualifier
EmailAddr
ExtKeyUsage
HostIdMap
JurCountry
JurLocality
JurStateProv
KeySize
KeyUsage
Label
Locality
Mail
NotAfter
NotBefore
NotifyEmail
Org
OrgUnit
PassPhrase
PostalCode
PublicKey
Requestor
Security
SerialNumber
SignWith
StateProv
Street
Title
Uid
UnstructAddr
UnstructName
UserId

A form field tag has the form:

<tns:Name formtype="InstallationSpecified | AdminSpecified | UserSpecified" 
                  initvalue="xxxxx" 
                  optional=”true | false” 
                  JSPfilename=”xxx.jsp”/>

where

Name

is the name of the form field, for example AltOther or Security.

formtype

can have one of the following values:

UserSpecified: The form field appears on the certificate request Web page where the user can enter data.
InstallationSpecified: The value is provided by the XML template and is not displayed on the certificate request Web page. Instead, there is a hidden form field on the certificate request Web page that specifies the value.
AdminSpecified: The administration Approve with Modification Web page should always display this form field and allow an administrator to specify a value for it.

The default for formtype is UserSpecified.

initvalue

The initial value of the form field. If formtype is AdminSpecified or UserSpecified, the form field is displayed with this initial value set but modifiable. If formtype is Installation Specified, this initial value is given to the hidden form field and it cannot be changed for the certificate request.

optional

Indicates whether this form field is optional. For UserSpecified form fields, optional indicates whether a value must be provided on the Certificate Request Web page. For AdminSpecified form fields, optional indicates whether a value must be provided on the administrator’s Approve with Modifications Web page. For InstallationSpecified form fields, the optional attribute is ignored. The default value for optional is false, and the form field is required.

JSPfilename

The filename of a JSP file that is included to display and validate the form field. The file that is included is a modifiable include file in the mod_inc directory with your Web application’s EAR file. If formtype is Installation Specified, JSPfilename is ignored.

The default value for JSPfilename is the name of the form field, in lowercase, combined with the .jsp extension. For example, the default value for JSPfilename for the form field tag for PassPhrase would be passphrase.jsp.

Rules: You can write your own JSP files to process form fields, but they must conform to the following rules:

The HTML form field, whether it is a select field, an input field, a text area field, or a hidden form field, must have the same name as the form field tag, but in lower case. For example, for the tag
```
<tns:CommonName formtype="AdminSpecified" optional="true" JSPfilename=”cn.jsp”/>
```
the form field must have the name commonname in the file cn.jsp.
The HTML form field must contain a JavaScript function with the name Valid concatenated with the lowercase form field name. For example, for the tag
```
<tns:CommonName formtype="AdminSpecified" optional="true" JSPfilename=”cn.jsp”/>
```
cn.jsp must contain a JavaScript method named Validcommonname. This JavaScript method should verify the form field and return true if it is valid and false if not. If there is no verification to be done, the Validformfieldname method can return true in all cases.

Each of the attributes (formtype, initvalue, optional and JSPfilename) can be omitted and defaulted.

Examples of form field tags:

<tns:CommonName formtype="AdminSpecified" optional="true" JSPfilename=”cn.jsp”/>
<tns:PassPhrase />