319 lines
9.0 KiB
HTML
319 lines
9.0 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Sign User Certificate Request (QYCUSUC) API</title>
|
|
<!-- Begin Header Records ========================================= -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- Created by Barb Smith for V5R2 -->
|
|
<!-- Edited by Kersten Jan 02 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>Sign User Certificate Request (QYCUSUC) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="50%">Signed certificate</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Signed certificate length</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Certificate request</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">E-mail address</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Returned Value:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%"> </td>
|
|
<td align="left" valign="top" width="50%">Return code</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Sign User Certificate Request (QYCUSUC) API signs a user certificate
|
|
request using the local Certificate Authority (CA). The request to sign the
|
|
user certificate request must come from an Internet Explorer, or compatible,
|
|
browser session. The call to this program must be made using the DTW_DIRECTCALL
|
|
language environment in Net.Data.</p>
|
|
|
|
<p>Error information is returned as a return value from this program. The error
|
|
code value can be captured using the RETURNS keyword on the function definition
|
|
that uses DTW_DIRECTCALL.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
<dt><em>User Profile Authority</em></dt>
|
|
|
|
<dd>Caller of this API must have *ALLOBJ and *SECADM special authorities</dd>
|
|
|
|
<dt><em>API Public Authority</em></dt>
|
|
|
|
<dd>*USE</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Signed certificate</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>The storage for returning the signed certificate. The signed certificate
|
|
will be a NULL terminated string. This storage is allocated by Net.Data and is
|
|
referenced using the environment variable that was specified on the call.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Signed certificate length</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The length of the storage provided by the signed certificate parameter.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Certificate request</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The certificate request data to sign. This should be the data that is
|
|
returned from the Enroll.CreatePKCS10() call in Net.Data.</p>
|
|
</dd>
|
|
|
|
<dt><strong>E-mail address</strong></dt>
|
|
|
|
<dd>Input; CHAR(*)
|
|
|
|
<p>The e-mail address for the user. This may be a NULL string.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Return Codes</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<tr>
|
|
<th align="center" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="15%">0</td>
|
|
<td align="left" valign="top" width="85%">Certificate was successfully
|
|
signed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">-99</td>
|
|
<td align="left" valign="top">Unexpected error.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">71</td>
|
|
<td align="left" valign="top">Unable to allocate storage. The certificate
|
|
request data may not be valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">93</td>
|
|
<td align="left" valign="top">The local Certificate Authority (CA) does not
|
|
exist. Use Digital Certificate Manager (DCM) to create the local CA.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">95</td>
|
|
<td align="left" valign="top">The password for the Local Certificate Authority
|
|
(CA) certificate store is not stashed. Use DCM to change the password for the
|
|
Local CA certificate store.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">321</td>
|
|
<td align="left" valign="top">Signed certificate length is not large enough to
|
|
return the signed certificate.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3845</td>
|
|
<td align="left" valign="top">The caller of this API does not have *ALLOBJ and
|
|
*SECADM special authorities.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3956</td>
|
|
<td align="left" valign="top">The local CA does not allow creation of user
|
|
certificates. You must change the policy data for the local CA using DCM.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4003</td>
|
|
<td align="left" valign="top">Certificate request to be signed is not
|
|
valid.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Example</h3>
|
|
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
|
for information pertaining to code examples.</p>
|
|
|
|
<p>The following is an example of a function call to this program using
|
|
Net.Data from an Internet Explorer browser session. Note that the size
|
|
specified for the second parameter must be the same as the number of characters
|
|
allocated for the first parameter.</p>
|
|
|
|
<pre>
|
|
%function(DTW_DIRECTCALL) signcert(OUT CHAR(5000) signedCert,
|
|
IN INT signedCertLen,
|
|
IN CHAR(4000) certData,
|
|
IN CHAR(128) email) RETURNS(retVal) {
|
|
%EXEC { /QSYS.LIB/QICSS.LIB/QYCUSUC.PGM %}
|
|
%}
|
|
</pre>
|
|
|
|
<p>The following is an example of code to generate a certificate request.</p>
|
|
|
|
<p>The form statement would look something like this:</p>
|
|
|
|
<pre>
|
|
<form name="UserCertForm" method=POST action="nextHTML" onSubmit="return makereq()">.
|
|
</pre>
|
|
|
|
<p>This code would need to be defined in the HTML before the JavaScript.</p>
|
|
|
|
<pre>
|
|
<OBJECT classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"
|
|
CODEBASE="xenroll.dll"
|
|
id=Enroll>
|
|
</OBJECT>
|
|
</pre>
|
|
|
|
<p>This is a JavaScript function that would be defined along with the HTML form
|
|
that is used to collect the necessary data to create the certificate
|
|
request.</p>
|
|
|
|
<pre>
|
|
function makereq() {
|
|
var checkResult = "";
|
|
var distNamePurpose = "";
|
|
var distName = "";
|
|
var certData = "";
|
|
var errStr = "";
|
|
|
|
// Still need to make sure that the fields are OK
|
|
checkResult = validate(); // Function that will check the validity of the
|
|
// data, such as making sure required fields are
|
|
// filled in and that the state field is at least
|
|
// 3 chars, etc.
|
|
if (checkResult == true) {
|
|
// Create the distinguished name from the input fields
|
|
distName = "C=" + document.UserCertForm.countryregion.value;
|
|
distName += ";ST=" + document.UserCertForm.stateprov.value;
|
|
distName += ";L=" + document.UserCertForm.locality.value;
|
|
distName += ";O=" + document.UserCertForm.orgname.value;
|
|
distName += ";OU=" + document.UserCertForm.orgunitname.value;
|
|
distName += ";CN=" + document.UserCertForm.commonname.value;
|
|
|
|
Enroll.KeySpec = 1;
|
|
Enroll.GenKeyFlags = 1;
|
|
distNamePurpose = "1.3.6.1.4.1.311.2.1.21";
|
|
certData = Enroll.CreatePKCS10(distName, distNamePurpose);
|
|
|
|
if (certData == "") {
|
|
// Certificate generation failed - put up an alert or something
|
|
errStr = "The certificate request was not created";
|
|
alert(errStr);
|
|
return (false);
|
|
}
|
|
else {
|
|
// Certificate generation OK - submit the request
|
|
document.UserCertForm.certData.value = certData;
|
|
return (true);
|
|
}
|
|
}
|
|
else
|
|
return (false);
|
|
}
|
|
</pre>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|