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.)Start of change
# =====================================================================
#
# 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. If approved, the certificate becomes valid after
#            it's requested.
#            (You may delay the valid date by specifying a non zero
#             number for the value of 'NotBefore',
#             eg. NotBefore=5. That means if the request is approved,
#             the certificate will become valid 5 days after it's
#             requested.)
#            HostidMap is formed by putting %%Userid%% and
#            %%HostIdMap=@host-name in the APPL section.
#
# 2@DHD
#
# Other than the user input fields, all other information is hard coded.
#
# User input fields:
#  Requestor - optional
#  PassPhrase - required
#  PublicKey - required (Provided by the browser itself)
#  NotifyEmail - optional
#
#  The presence of CommonName without a value tells SAF to determine
#  the CN value from the PGMRNAME field of the user's USER profile.
#  See the RACF Callable Services Guide for more information
#
#  RACF userid/password authentication : required
#  Administrator approval              : not required
#
#
# =====================================================================
#
<TEMPLATE NAME=2-Year PKI Browser Certificate For Authenticating To z/OS>  2 
<TEMPLATE NAME=PKI Browser Certificate>
<NICKNAME=2YBZOS>
#<AUTORENEW=Y>
<CONTENT>  3 
#@LMA
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<HTML lang="en"><HEAD>
#@LTM
%%-copyright%%  4 
<TITLE> Web Based PKIX Certificate Generation Application Pg 2</TITLE>  5 
%%-ObjectHeaderIE[osversion]%%
<SCRIPT LANGUAGE="JavaScript">
<!--
function init()
{
  // 1@02D
  LoadCSPs();
}
//-->
</SCRIPT>
</HEAD>

<BODY onload="init();">
<div role="main"><H1>2-Year PKI Browser Certificate For Authenticating To z/OS  6 </H1>
<div role="region" aria-label="Options">
<p>
<H2>Choose one of the following:</H2>
<p>
<ul>
<li>
<div role="region" aria-label="Request A New Certificate">
<h3>Request a New Certificate</h3>
# This ACTION forces userid/pw authentication and runs the task under
# the client's ID
#<FORM NAME="CertReq" METHOD=POST ACTION=  7 
#                "/[application]/ssl-cgi-bin/auth/careq.rexx" onSubmit=

# This ACTION forces userid/pw authentication but runs the task under
# the surrogate ID
 <FORM NAME="CertReq" METHOD=POST ACTION=
               "/[application]/ssl-cgi-bin/surrogateauth/careq.rexx" onSubmit=

# This ACTION is for non z/OS clients. The task runs under the
# surrogate ID
#<FORM NAME="CertReq" METHOD=POST ACTION=
#              "/[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 
#-- User input fields and validation Javascript ---------------
<SCRIPT LANGUAGE="JavaScript">  9 
<!--
function ValidateEntry(frm){
  if (ValidRequestor(frm) &&
   ValidNotifyEmail(frm) &&
   ValidPassPhrase(frm) &&
   ValidPublicKey(frm)){
# Add your validation Javascript here if needed ---
 return true;
}
else
 return false;
}
//-->
</SCRIPT>
 %%Requestor (optional)%%
 %%NotifyEmail (optional)%%
 %%PassPhrase%%
 %%PublicKey[browsertype]%%
#-- End user input fields and validation Javascript -----------
<p>
<INPUT TYPE="Submit" VALUE="Submit certificate request">
<INPUT TYPE="reset" VALUE="Clear">
</FORM>
</div>
</li>
<li>
<div role="region" aria-label="Pick Up a Previously Issued Certificate">
<H3>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>
</div>
</li>
</ul>
</div>
<p>%%-pagefooter%%  10 
</div>
</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 
#@LMA
<!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">
<!--
function MissingTransIdAlert(){
var STRING_MissingTransIdPrompt=
    "Enter the transaction ID assigned to the certificate.";
if(document.retrieveform.TransactionId.value==""){
 alert(STRING_MissingTransIdPrompt);
 document.retrieveform.TransactionId.focus();
 return true;
}
else {
 return false;
 }
}
//-->
</SCRIPT>
</HEAD>

<BODY>
<div role="main"><H1> Retrieve Your [tmplname]</H1>  16 
<H3>Please bookmark this page</h3>
<p>Since your certificate may not have been issued yet, we recommend
that you create a bookmark to this location so that when you return to
this bookmark, the browser will display your transaction ID.
This is the easiest way to check your status.

# This ACTION forces userid/pw authentication and runs the task
# under the client's ID
#<FORM NAME=retrieveform METHOD=POST ACTION=  17 
#      "/[application]/ssl-cgi-bin/auth/cagetcert.rexx" onSubmit=
#
# This ACTION forces userid/pw authentication but runs the task
# under the surrogate ID
 <FORM NAME=retrieveform METHOD=POST ACTION=
       "/[application]/ssl-cgi-bin/surrogateauth/cagetcert.rexx" onSubmit=
#
# This ACTION is for non z/OS clients. The task runs under surrogate ID
#<FORM NAME=retrieveform METHOD=POST ACTION=
#      "/[application]/ssl-cgi-bin/cagetcert.rexx" onSubmit=
      "return ValidateEntry(this)">
<INPUT NAME="Template" TYPE="hidden" VALUE="[tmplname]">
#-- User input fields and validation Javascript ---------------
<SCRIPT LANGUAGE="JavaScript">
<!--
function ValidateEntry(frm){
if (ValidTransactionId(frm) &&
    ValidChallengePassPhrase(frm)) {
# Add your own Javascript here if needed
 return true;
}
else
 return false;
}
//-->
</SCRIPT>
 %%-TransactionId%%
 %%ChallengePassPhrase (optional)%%
#-- End user input fields and validation Javascript -----------
<p>
<INPUT TYPE="submit" VALUE="Retrieve and Install Certificate">
</FORM>
</div>
<div role="region" aria-label="Home Page">
<FORM METHOD=GET ACTION="/[application]/public-cgi/camain.rexx">
<INPUT NAME="Template" TYPE="hidden" VALUE="[tmplname]">
<INPUT TYPE="submit" VALUE="Home Page">
</FORM>
</div>
<p>%%-pagefooter%%
</BODY>
</HTML>
</RETRIEVECONTENT>
<RETURNCERT>  18 
%%returnbrowsercert[browsertype]%%
</RETURNCERT>
</TEMPLATE>
End of change The numbers in the following list refer to the highlighted tags in the preceding excerpt of the TEMPLATE section.
  1. The template begins with a block comment identifying the template and explaining its use and fields.
  2. 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.
  3. 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.)
  4. The %%-copyright%% named field displays the copyright statement.
  5. The title contains the heading that appears at the top of the browser when the web page is displayed.
  6. The heading is the main heading on the web page for requesting the selected certificate.
  7. The ACTION tag indicates that the CGI script that gets control when the user clicks the Submit certificate request button is careq.rexx.
  8. 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.
  9. This JavaScript script provides the underlying logic for the text entry that the user must perform.
  10. The %%-pagefooter%% named field is defined in the INSERT section (shown later). This contains the email address of the PKI Services administrator.
  11. 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.)
  12. The CONSTANT subsection has hardcoded values to use, for example (for the non-SAF certificates), the signing certificate is PKI:.
  13. 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.)
  14. 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.)
  15. 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.
  16. The main heading on the web page is "Retrieve Your (Name of Certificate)".
  17. The ACTION is to call cagetcert.rexx as list item 15 indicates.
  18. The RETURNCERT subsection contains the %%return10cert%% named field, which is defined in an INSERT. (See list item 4.)
Parent topic: Examining the pkiserv.tmpl file