TEMPLATE sections

<TEMPLATE NAME=1-Year PKI SSL Browser Certificate>
<TEMPLATE NAME=PKI Browser Certificate>
<NICKNAME=1YBSSL>

The true name of a certificate template is its actual complete name. This is the name in the first line, 1-Year PKI SSL Browser Certificate. However, you can refer to a single template by more than one name by using an alias. The template name in the second line, PKI Browser Certificate, is an alias. An alias differentiates browser from server certificates. Finally, renewing a certificate requires recalling the template name, so the template name must be stored with the certificate. The NICKNAME (or short name) serves this purpose.

<TEMPLATE NAME=1-Year PKI SSL Browser Certificate>
<TEMPLATE NAME=PKI Browser Certificate>
<NICKNAME=1YBSSL>
<AUTORENEW=Y>

<CONTENT>…</CONTENT>

This subsection contains the HTML to display a web page to the end user requesting a certificate of a specific type. (See Figure 1 for a sample web page.) Field names on the certificate request (such as a text box where the user enters a value for Common Name) match the names of INSERT sections. The following examples show the INSERT sections corresponding to the field names %%CommonName%% and %%Requestor (optional)%%.

Examples:

<INSERT NAME=CommonName> 
<p><LABEL for="commonnamefield">Common Name [optfield]</LABEL><BR>
<INPUT NAME="CommonName" TYPE="text" SIZE=64  maxlength="64"	id="commonnamefield">

<INSERT NAME=Requestor>
<p><LABEL for="requestorfield">Your name for tracking this request [optfield]</LABEL><BR>
<INPUT NAME="Requestor" TYPE="text" SIZE=32 maxlength="32" id="requestorfield">

Named fields in this subsection are optional if the named field contains more that one word within the %% delimiters (as in %%Requestor (optional)%%). The user need not supply a value for Requestor.

<APPL>…</APPL>

This subsection identifies certificate fields for which the application itself should provide values. This subsection should contain only named fields, one per line. The only supported named fields that are allowed in this section are:

• UserId
• HostIdMap

Example:

<APPL>
 %%UserId%%
 %%HostIdMap=@www.ibm.com%%
<APPL>

<CONSTANT>…</CONSTANT>

This subsection identifies certificate fields that have a constant (hardcoded) value for everyone. This subsection should contain only named fields, one per line. The syntax for specifying the values is %%field-name=field-value%%:

Example:

%%KeyUsage=handshake%%

In addition to the named fields listed in Table 1, you can also include the following named fields in this subsection only.

Critical

Identifies a certificate extension that is to be marked critical in the issued certificates. This name-value pair can be repeated for each extension to be marked critical. Here is the list of acceptable values for Critical:

• BasicContraints (ignored as this extension is always marked critical)
• KeyUsage (ignored as this extension is always marked critical)
• ExtKeyUsage
• SubjectAltName, AltEmail, AltIPAddr, AltDomain, AltURI
• HostIdMappings, HostIdMap
• CertificatePolicies, CertPolicies

Example:

%%Critical=ExtKeyUsage%%

Rules:

1. If you have specified configuration file setting PolicyRequired=T, then specifying %%Critical=CertPolicies%% is ignored. The configuration file setting PolicyCritical determines if the CertificatePolicies extension is marked critical. See Using certificate policies for more information.
2. When ExtKeyUsage is extracted from an input PKCS #10 certificate request, the critical flag in the request is ignored. Therefore, setting %%Critical=ExtKeyUsage%% is the only way to get the ExtKeyUsage extension marked critical.

CertPolicies

Identifies the certificate policies that are to be included in the issued certificates. The value is a vector of numbers each representing one of the PolicyNamen values that are specified in the CertPolicy section of the configuration file.

Example:

%%CertPolicies=3 6 10%%

Rule: If you specified configuration file setting PolicyRequired=T, then specifying %%CertPolicies=any-value%% is ignored. All issued certificates have the same certificate policies as defined in the configuration file. See Using certificate policies for more information.

AuthInfoAcc

Indicates the information necessary for the AuthorityInfoAccess extension. The value specifies a two-part, comma-separated string identifying the access method (OCSP or IdentrusOCSP) and the access URL. The URL must be specified in HTTP-protocol format only. (LDAP protocol is not supported.) The name-value pair can be repeated for each value that is required in the extension.

Examples:

%%OCSP,URL=https://ocsp.vendor.com%%
%%IdentrusOCSP,URI=https://identrus200.identrus.com%%
%%OCSP,URI=http://www.mycompany.com/PKIServ/public-cgi/caocsp%%

<ADMINAPPROVE>…</ADMINAPPROVE>

This optional subsection contains the named fields that the administrator can modify when approving certificate requests. (The named fields refer to INSERT sections.) When an end user requests a certificate, the certificate request might contain fields that the end user cannot see. When approving a request, the administrator can modify:

• Fields that are present and visible to the end user in the certificate request, for example Common Name
• Fields that are not visible to the end user but are hardcoded (in the CONSTANT subsection) in the template, for example Organizational unit
• Fields that are not visible to the end user and that the PKI Services administrator can add, for example, HostIdMappings extension or an empty Organizational Unit field (these are listed in the <ADMINAPPROVE> section, and either the end user did not fill them in or they are not present on the template request form).

The presence of this section (even if empty) indicates that an administrator must approve this request. The absence of this section indicates using auto-approval.

Note: In the pkiserv.tmpl certificate templates file, the only certificate templates that are auto-approved are:

• One-year SAF server certificate
• One-year SAF browser certificate
• Two-year PKI browser certificate for authenticating to z/OS
• Five-year PKI intermediate CA server certificate

The following tags are allowed in the ADMINAPPROVE section:

• ADMINNUM
• AltDomain
• AltEmail
• AltIPAddr
• AltOther_OID
• AltURI
• AuthInfoAcc
• CertPolicies
• CommonName
• Country
• Critical
• CustomExt
• DNQualifier
• DomainName
• EmailAddr
• EndDate
• ExtKeyUsage
• HostIdMap (can repeat)
• JurCountry
• JurLocality
• JurStateProv
• KeyUsage
• Locality
• Mail
• Org
• OrgUnit (can repeat)
• PostalCode
• SerialNumber
• StartDate
• StateProv
• Street
• Title
• Uid
• UnstructName
• UnstructAddr

Note: The following fields are not modifiable and are ignored in the ADMINAPPROVE section:

• Label
• PublicKey
• Requestor
• SignWith
• UserId

(For information about fields, see Table 1.)

Example:

<ADMINAPPROVE>
%%KeyUsage%%
%%CommonName%%
%%OrgUnit%%
%%Org%%
%%Country%%
%%HostIdMap%%
%%HostIdMap%%
%%HostIdMap%%
%%HostIdMap%%
<ADMINAPPROVE>

The ADMINNUM tag is optional. It indicates the number of PKI Services administrators that must approve certificate requests that are using this template before certificates are issued for them. This tag has the form <ADMINNUM=value>, where value is a numeric value from 1 to 32. The tag has the following meanings:

• By default, all certificate requests require approval by one PKI Services administrator. If the ADMINNUM tag is not present, all certificate requests that use this template require approval by one PKI Services administrator before issuing a certificate.
• If the ADMINNUM tag does not occur within the ADMINAPPROVE subsection, PKI Services operates as if the tag is not present.
• If the ADMINNUM value is greater than 32, a value of 32 is used.
• If the ADMINNUM value is less than one or is a non-numeric value, a value of 1 is used.

Note: A request remains in Pending Approval state until the required number of individual administrative approvals is made for the request, at which time the request changes to Approved state. If an administrator issues an Approve with Modifications on a request that is in Pending Approval state, any previously made approvals are nullified, and the number of approvals that are made for the request is reset to 1.

Example:

<ADMINAPPROVE>
<ADMINNUM=4>
%%KeyUsage%%
%%CommonName%%
%%OrgUnit%%
%%Org%%
%%Country%%
%%HostIdMap%%
%%HostIdMap%%
%%HostIdMap%%
%%HostIdMap%%
<ADMINAPPROVE>

<SUCCESSCONTENT>…</SUCCESSCONTENT>

This subsection contains the HTML to display to the end user a web page indicating that the certificate request was submitted successfully. Any named fields in this subsection are interpreted as content inserts defined by INSERT sections. For PKISERV, the INSERT sections are included as part of the HTML to display a web page to the end user.

In all of the templates included with PKI Services, <SUCCESSCONTENT> contains only the named field %%-requestok%%. (See What are named fields? for an explanation of named fields.) This contains HTML for the web page "Request submitted successfully". (For a sample of this web page, see Figure 3.)

<FAILURECONTENT>…</FAILURECONTENT>

This subsection contains the HTML to display to the end user a web page indicating the certificate request was not submitted successfully. Any named fields in this subsection are interpreted as content inserts defined by INSERT sections. For PKISERV, the INSERT sections are included as part of the HTML to display a web page to the end user.

In all of the templates included with PKI Services, <SUCCESSCONTENT> contains only the named field %%-requestbad%%. (See What are named fields? for an explanation of named fields.) This contains HTML for the web page that says, "Request was not successful".

<RETRIEVECONTENT>…</RETRIEVECONTENT>

This subsection contains the HTML to display to the end user a web page to enable certificate retrieval. Any named fields in this subsection are interpreted as content inserts that the INSERT sections define. For PKISERV, the INSERT sections are included as part of the HTML presented to the end user.

For a sample of a web page this section generates, see Figure 4. You might want to look at this web page while reading the following explanation:

In all of the templates included with PKI Services, <RETRIEVECONTENT> contains:

• The named field %%-copyright%%, which displays any copyright information. (See What are named fields? for an explanation about named fields.)
• The title of the web page (This appears in the banner of your browser. Figure 4 does not include the banner header but shows only the frame containing the content and not the browser window displaying the content.)
• A JavaScript script for processing the fields that the user enters on the web page.
• A heading that says "Retrieve Your (name of certificate)". This uses the substitution variable [tmplname]. (See What are substitution variables? for an explanation of substitution variables.)
• Text: a heading and paragraph about bookmarking this web page.
• The named field %%TransactionId%% - A field where you enter your transaction ID if it is not already displayed.
• A field where you enter the passphrase you entered on the certificate request form.

<RETURNCERT>…</RETURNCERT>

This subsection contains the HTML to display a web page upon successful certificate retrieval. The formats are:

• A browser certificate that can be installed into the browser.
• A server certificate that is displayed in B64 format.
• A PKCS #12 package, which contains the private key. For a browser or server certificate, this can be a single certificate or a certificate chain, depending on the authority of the user ID that does the retrieval. For a certificate with a key pair generated by PKI Services, the PKCS #12 package contains the requested certificate and its issuer certificate.

<PREREGISTER>…</PREREGISTER>

This optional subsection indicates the creation of a preregistration record and contains the Simple Certificate Enrollment Protocol (SCEP) rules for approval of a SCEP request. (For details, see Overview of certificate request processing for preregistered SCEP clients.)

Example:

<PREREGISTER>
AuthenticatedClient=AutoApprove
SemiauthenticatedClient=AdminApprove
UnauthenticatedClient=Reject
SubsequentRequest=AutoApprove
RenewalRequest=AutoApprove
</PREREGISTER>

The ADMINNUM tag is optional. It indicates the number of PKI Services administrators that must approve certificate requests for clients that are marked as AdminApprove before certificates are issued for those clients. This tag has the form <ADMINNUM=value>, where value can be a numeric value from 1 to 32. The tag has the following meanings:

• By default, all requests for clients that are marked as AdminApprove require the approval of one PKI Services administrator. If the ADMINNUM tag is not present, all certificate requests for clients that are marked as AdminApprove require approval by one PKI Services administrator before issuing a certificate.
• If the ADMINNUM tag does not occur within the PREREGISTER subsection, PKI Services operates as if the tag is not present.
• If the ADMINNUM value is greater than 32, a value of 32 is used.
• If the ADMINNUM value is less than one or is a non-numeric value, a value of 1 is used.

Note: A request remains in Pending Approval state until the required number of individual administrative approvals is made for the request, at which time the request changes to Approved state. If an administrator issues an Approve with Modifications on a request that is in Pending Approval state, any previously made approvals are nullified, and the number of approvals that are made for the request is reset to 1.

Example:

<PREREGISTER>
<ADMINNUM=4>
AuthenticatedClient=AutoApprove
SemiauthenticatedClient=AdminApprove
UnauthenticatedClient=Reject
SubsequentRequest=AutoApprove
RenewalRequest=AutoApprove
</PREREGISTER>

In this example:

• SCEP requests originating from authenticated clients are automatically approved, and do not require an explicit approval from a PKI Services administrator.
• SCEP requests originating from a semi-authenticated client require approvals from four PKI Services administrators before a certificate is issued.
• SCEP requests originating from any unauthenticated clients are automatically rejected without an explicit action from a PKI Services administrator.
• Requests for more certificates from previously authenticated SCEP clients, including SCEP requests to renew certificates, are automatically approved, and do not require an explicit approval from a PKI Services administrator.