|
TEMPLATE sections define the fields that comprise a specific certificate
request. They define the certificate templates referenced in the APPLICATION
section. The pkiserv.tmpl certificate templates file
contains a TEMPLATE section for each of the certificates described
in Table 1.
Each template section begins with one or more template names. - <TEMPLATE NAME=tmpl-name>…</TEMPLATE
NAME>
- The pkiserv.tmpl certificate templates file that
ships with PKI Services includes
lines like the following example:
Example: <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 simply 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.
Note: - You can have more than one alias. (Use an additional <TEMPLATE
NAME=alias> line for each one.)
- The value of a NICKNAME is an 8-character string.
- SAF certificate templates do not include nicknames.
Table 1 shows
the true name, alias, and nickname for each certificate template: Table 1. Names, aliases, and nicknames
of certificate templatesTrue name |
Alias |
Nickname |
---|
1-Year PKI SSL Browser Certificate |
PKI Browser Certificate |
1YBSSL |
1-Year PKI S/MIME Browser Certificate |
PKI Browser Certificate |
1YBSM |
1-Year PKI Generated Key Certificate |
PKI Key Certificate |
1YKRC |
2-Year EV SSL Server Certificate |
PKI Server Certificate |
2YEVSSL |
2-Year PKI Browser Certificate For Authenticating
To z/OS® |
PKI Browser Certificate |
2YBZOS |
2-Year PKI Authenticode - Code Signing Certificate |
PKI Server Certificate |
2YIACS |
2-Year PKI Windows Logon
Certificate |
PKI Browser Certificate |
2YBWL |
5-Year PKI SSL Server Certificate |
PKI Server Certificate |
5YSSSL |
5-Year PKI IPSEC Server (Firewall) Certificate |
PKI Server Certificate |
5YSIPS |
5-Year PKI Intermediate CA Certificate |
PKI Server Certificate |
5YSCA |
5-Year SCEP Certificate - Preregistration |
— |
5YSCEPP |
n-Year PKI Certificate for Extensions
Demonstration |
PKI Browser Certificate |
SAMPLB |
1-Year SAF Browser Certificate |
SAF Browser Certificate |
— |
1-Year SAF Server Certificate |
SAF Server Certificate |
— |
The AUTORENEW tag is optional. It determines
whether the certificate is to be automatically renewed when it approaches
expiration. This tag has the form <AUTORENEW= value>,
where value can have the value Y, y, N,
or n. If the AUTORENEW tag has any other value, or
does not immediately follow the NICKNAME tag, PKI Services operates
as if the tag is not present. The tag has the following meanings: - AUTORENEW tag not present means that the certificate is not set
up for automatic renewal.
- AUTORENEW=Y means that the certificate is enabled for automatic
renewal.
- AUTORENEW=N means that the certificate is eligible for automatic
renewal, but automatic renewal is disabled.
Note: Adding the AutoRenew=Y
will not enable all certificates to be AutoRenewed. It will enable
only the newly issued certificates after the template has been updated.
For more information on how AutoRenew processing should be added,
see Using the administration Web pages.
See Setting up automatic renewal of certificates for more information.
Example: <TEMPLATE NAME=1-Year PKI SSL Browser Certificate>
<TEMPLATE NAME=PKI Browser Certificate>
<NICKNAME=1YBSSL>
<AUTORENEW=Y>
TEMPLATE
sections can have the following subsections: - CONTENT
- APPL
- CONSTANT
- ADMINAPPROVE
- SUCCESSCONTENT
- FAILURECONTENT
- RETRIEVECONTENT
- RETURNCERT
- PREREGISTER
- <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 allowed
in this section are:
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:- If you have specified configuration file setting PolicyRequired=T,
then specifying %%Critical=CertPolicies%% will be
ignored. The configuration file setting PolicyCritical will determine
if the CertificatePolicies extension is marked critical. See Using certificate policies for more information.
- 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 specified in the CertPolicy section
of the configuration file.
Example:%%CertPolicies=3 6 10%%
Rule: If
you have specified configuration file setting PolicyRequired=T,
then specifying %%CertPolicies=any-value%% will
be ignored. All issued certificates will 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 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
You can put the following fields in
the ADMINAPPROVE section: - 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>
- <SUCCESSCONTENT>…</SUCCESSCONTENT>
- This
subsection contains the HTML to display to the end user a Web page
saying 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
saying 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 of 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 the user enters 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>
|