Examining the TEMPLATE section

The TEMPLATE section follows the APPLICATION section and contains several sample templates. The following example is an excerpt from the TEMPLATE section of the pkiserv.tmpl file. (The vertical ellipses indicate omitted sections.)

# ========================================================================= 
#
# Template Name - 2-Year PKI Browser Certificate For Authenticating
#                 to z/OS  1 
#
# Function - Creates a 2-Year certificate good for authenticating to z/OS.
⋮
# User input fields:
#  Requestor - optional
#  PassPhrase - required
#  PublicKey - required (Provided by the browser itself)
#  NotifyEmail - optional
⋮
# =========================================================================
#
<TEMPLATE NAME=2-Year PKI Browser Certificate For Authenticating To z/OS>  2 
<TEMPLATE NAME=PKI Browser Certificate>
<NICKNAME=2YBZOS>
<AUTORENEW=Y>
<CONTENT>  3 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML lang="en"><HEAD>
<TITLE> Web Based PKIX Certificate Generation Application Pg 2</TITLE>  4 
%%-copyright%%  5 
%%-AdditionalHead[browsertype]%%
</HEAD>

<BODY>
<H1>2-Year PKI Browser Certificate For Authenticating To z/OS</H1>  6 
<p>
<H2>Choose one of the following:</H2>
⋮
#<FORM NAME="CertReq" METHOD=POST ACTION=  7 
#              "/[application]/ssl-cgi-bin/careq.rexx" onSubmit=
    "return ValidateEntry(this)">

<INPUT NAME="Template" TYPE="hidden" VALUE="[tmplname]">
<p> Enter values for the following field(s)  8 
<SCRIPT LANGUAGE="JavaScript">  9 
<!--
⋮
//-->
</SCRIPT>
 %%Requestor (optional)%%
 %%NotifyEmail (optional)%%
 %%PassPhrase%%
 %%PublicKey2[browsertype]%%

<p>
<INPUT TYPE="Submit" VALUE="Submit certificate request">
<INPUT TYPE="reset" VALUE="Clear">
</FORM>
<p>
<H3><li>Pick Up a Previously Issued Certificate</H3>
<FORM METHOD=GET ACTION="/[application]/ssl-cgi/caretrieve.rexx"> 
<INPUT NAME="Template" TYPE="hidden" VALUE="[tmplname]">
<INPUT TYPE="submit" VALUE="Retrieve your certificate">
</FORM>
</ul>
<p>%%-pagefooter%%  10 
</BODY>
</HTML>
</CONTENT>
<APPL>  11 
 %%UserId%%
 %%HostIdMap=@host-name%%
</APPL>
<CONSTANT>  12 
 %%CommonName=%%
 %%OrgUnit=Class 1 Internet Certificate CA%%
 %%Org=The Firm%%
 %%KeyUsage=handshake%%
 %%ExtKeyUsage=clientauth%%
 %%NotBefore=0%%
 %%NotAfter=730%%
 %%SignWith=PKI:%%
</CONSTANT>
<SUCCESSCONTENT>  13 
 %%-requestok%%
</SUCCESSCONTENT>
<FAILURECONTENT>  14 
 %%-requestbad%%
</FAILURECONTENT>

<RETRIEVECONTENT>  15 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML lang="en"><HEAD>
%%-copyright%%
<TITLE> Web Based PKIX Certificate Generation Application Pg 3</TITLE>
<SCRIPT LANGUAGE="JavaScript">
<!--
⋮
//-->
</SCRIPT>
</HEAD>

<BODY>
<H1> Retrieve Your [tmplname]</H1>  16 
<H3>Please bookmark this page</h3>
⋮
#<FORM NAME=retrieveform METHOD=POST ACTION=  17 
#      "/[application]/ssl-cgi-bin/cagetcert.rexx" onSubmit=
⋮
</FORM>
⋮
<p>%%-pagefooter%%
</BODY>
</HTML>
</RETRIEVECONTENT>
<RETURNCERT>  18 
%%returnbrowsercert[browsertype]%%
</RETURNCERT>
</TEMPLATE>

The numbers in the following list refer to the highlighted tags in the preceding excerpt of the TEMPLATE section.

The template begins with a block comment identifying the template and explaining its use and fields.
There are three names for each certificate (except for SAF templates, which do not include nicknames). The first TEMPLATE NAME line defines the true (actual, complete) name of the certificate. The next TEMPLATE NAME line defines an alias. (This simply differentiates browser from server certificates.) The NICKNAME defines an 8-character string. In each template for which you want certificates to be automatically renewed, insert the AUTORENEW tag immediately following the NICKNAME tag, if it is not already there, and set it to Y.
The CONTENT subsection contains the HTML to display a Web page to the end user requesting this type of certificate. (The CGI script catmpl.rexx displays this content.)
The title contains the heading that appears at the very top of the browser when the Web page is displayed.
The %%-copyright%% named field displays the copyright statement.
The heading is the main heading on the Web page for requesting the selected certificate.
The ACTION tag indicates that the CGI script that gets control when the user clicks the Submit certificate request button is careq.rexx.
Fields for which the user can supply input include %%Requestor%%, %%PassPhrase%%,%%NotifyEmail%%, and %%PublicKey2%%. (These fields are named fields that are defined in the INSERT section, which is shown later.) All fields not marked optional are required. %%PublicKey2%% contains the substitution variable, [browsertype]. This is replaced at run time with IE or NS, depending on the browser the user has. This is necessary because the browsers behave differently for key generation and certificates.
This JavaScript script provides the underlying logic for the text entry that the user must perform.
The %%-pagefooter%% named field is defined in the INSERT section (shown later). This contains the e-mail address of the PKI Services administrator.
The APPL subsection indicates the fields that careq.rexx itself provides, in this case, %%UserId%% and %%HostIdMap%%. (These are set from the IBM HTTP Server environment variable REMOTE_USER.)
The CONSTANT subsection has hardcoded values to use, for example (for the non-SAF certificates), the signing certificate is PKI:.
The SUCCESSCONTENT subsection contains the HTML to display upon successfully requesting the certificate. It includes the %%-requestok%% named field. (This is defined in the INSERT section, shown in Examining the INSERT section . See list item 1.)
The FAILURECONTENT subsection contains the HTML to display when the certificate request is unsuccessful. This subsection contains the %%-requestbad%% named field. (This named field is defined in the INSERT section, shown in Examining the INSERT section.)
The -requestok INSERT (mentioned in list item 13) includes an ACTION that calls caretrieve.rexx, which displays the HTML in the RETRIEVECONTENT subsection. The first time the Web page is displayed, it includes the transaction ID associated with the certificate request. If the user leaves the Web page and then returns, the transaction ID field must be filled in. Entering the transaction ID and clicking the Continue button calls cagetcert.rexx.
The main heading on the Web page is "Retrieve Your (Name of Certificate)".
The ACTION is to call cagetcert.rexx as list item 15 indicates.
The RETURNCERT subsection contains the %%return10cert%% named field, which is defined in an INSERT. (See list item 4.)