Sign User Certificate Request (QYCUSUC) API

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.

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.

Authorities and Locks

User Profile Authority

Caller of this API must have *ALLOBJ and *SECADM special authorities

API Public Authority

*USE

Required Parameter Group

Signed certificate

OUTPUT; CHAR(*)

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.

Signed certificate length

INPUT; BINARY(4)

The length of the storage provided by the signed certificate parameter.

Certificate request

INPUT; CHAR(*)

The certificate request data to sign. This should be the data that is returned from the Enroll.CreatePKCS10() call in Net.Data.

E-mail address

Input; CHAR(*)

The e-mail address for the user. This may be a NULL string.

Return Codes

Example

See Code disclaimer information for information pertaining to code examples.

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.

%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 %}
%}

The following is an example of code to generate a certificate request.

The form statement would look something like this:

<form name="UserCertForm" method=POST action="nextHTML" onSubmit="return makereq()">.

This code would need to be defined in the HTML before the JavaScript.

<OBJECT classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1"
        CODEBASE="xenroll.dll"
        id=Enroll>
</OBJECT>

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.

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);
}