Public Key Infrastructure (PKI) Authentication

This article contains the following topics:
casm1401
This article contains the following topics:
If you plan to use the PKI authentication, realize that the content of the login request is encrypted with a private key that can only be decrypted by its matching public key. The response of the login request is returned as plain text.
Generally, each application accessing CA SDM Web Services is assigned with a policy. CA SDM Web Services stores detailed information about a policy, along with the public key of a digital certificate. An application, as the policy holder, uses the private key of the digital certificate and the policy code (as policy identifier) to assemble a login request.
loginServiceManaged (Policy, Encrypted_Policy)
CA SDM Web Services performs the user authentication by locating the policy through the plain text policy code, retrieving the policy holder’s public key associated with the policy, decrypting the encrypted policy code, matching the decrypted content with the policy code, and finally, opening a session with a back-end server. The plain text session ID (SID) is returned and can be used for subsequent method invocations. Only the policyholder holds the private key that matches the policy’s associated public key stored in CA SDM.
All subsequent web services calls must include the returned session ID (SID). The Proxy contact specified in the policy is responsible for all web services activities initiated in this session. All function group security and data partition is enforced for the proxy contact.
The Encrypted_Policy parameter should be in the BASE64 text format. The user application must perform proper conversion from the binary format.
Policy is a required field. When you define it, use plain text policy code as defined in a policy. Encrypted_Policy (the digital signature of the policy code encrypted with the policy holder’s private key) is required. When you define Encrypted_Policy, use the algorithm SHA1 with RSA to obtain the digital signature.
Implement loginServiceManaged in Java
The following shows how to generate Certificates and then use these generated Certificates to access the CA SDM web services.
In the following example, the login process completes using the CA SDM Certificate and then performs two common web services calls. The getBopsid() web services method call allows you to obtain a token that is linked to a specific user. This token can be used to login to the CA SDM web interface as the linked user without being prompted for a password. This allows seamless integration to be enabled between different applications.
The generated BOPSID token expires after 30 seconds, so it must be used promptly.
There is a known issue when using the 1.4 version of the AXIS tool. For more information, see the 
Release Notes
.
Follow these steps:
  1. Generate the stub classes with AIXS Tool WSDL2Java. For more information, see the Generating Stub Classes with AXIS Tool WSDL2Java section from the PKI_loginServiceManaged_JAVA_steps file. Find the file in the following location:
    $NX_ROOT/samples/sdk/websvc/java/test1_pki
  2. Start the CA SDM service.
  3. Run pdm_pki -p DEFAULT.
    DEFAULT.p12 is created in the current directory. This policy will have the password equal to the policy name (in this case DEFAULT).
    This command will also add the Certificate's public key to the field pub_key field (public_key attribute) in the sapolicy table/object.
  4. Log in to CA SDM.
  5. Select SOAP Web Services Policy, Policies on the Administration tab.
    The SOAP Web Services Access Policy List page opens.
  6. Click DEFAULT.
    The SOAP Web Services Access Policy Detail page opens.
  7. Complete the Proxy Contact field (in this example, ServiceDesk) and confirm that the DEFAULT policy record Has Key field displays "Yes."
  8. Copy DEFAULT.p12 (from the directory where command pdm_pki is executed), the JSP file called
    pkilogin.jsp
    and the HTML file called
    pkilogin.htm
    (from the $NX_ROOT/samples/sdk/websvc/java/test1_pki directory) to the following directory:
    $NX_ROOT/bopcfg/www/CATALINA_BASE/webapps/axis
  9. Open the HTML form (from the axis directory). For example, http://localhost:8080/axis/pkilogin.htm
    Complete the appropriate fields.
    The Directory field identifies the location of the Certificate file. Modify the path to the correct location.
  10. Click Log me in!
    The results page opens.
  11. Click the BOPSID URL.
    Click this immediately! The BOPSID has a limited life token of about 30 seconds.
    The format of a URL using a BOPSID is as follows:
    http://<server name>:CA Portal/CAisd/pdmweb.exe?BOPSID=<BOPSID value>
In order to use the loginServiceManaged method for a Java client program running on AIX, you may need to replace a pair of security policy files within your JAVA_HOME. Go to http://www.ibm.com and search for "developerworks java technology security information AIX". In the "developerWorks : Java technology : Security" document, follow the link to "IBM SDK Policy files". Download the unrestricted policy files, local_policy.jar and US_export_policy.jar. Use these files to replace the original files in your JAVA_HOME/lib/security directory."
Configuration for the PKI Authentication Type
To configure for PKI authentication, you must first create an access policy. The process flow is as follows:
  • Create an Access Policy
    The administrator performs this task using the product (Web Interface only), and as part of the process, needs to assign a unique text code to each access policy.
  • Obtain a Digital Certificate with a Public/Private Key Pair and Associate it with the Access Policy
    For PKI access authentication, a user application needs to obtain a digital certificate that contains both a public key and private key pair. An administrator can obtain the digital certificate through third-party Certificate Authority (CA) or security products that support digital certificates. CA SDM also provides a server-side utility that can generate a digital certificate. It is located in <NX_ROOT>/bin directory as follows:
    pdm_pki - p policy_code [ - l certificate file] [ - f] [-h]
    • -p
      Identifies a unique policy code.
    • -f
      Allows the utility to replace the existing public key with a new public key.
    • -l
      Loads the public key stored in a X509 V3 certificate.
    • -h
      Displays help on the command line window.
    If you obtain a digital certificate through a third-party, CA Technologies, or security products, import it to where the CA SDM server is located, and then associate it to an access policy. The administrator of the user application should obtain a digital certificate file that includes the content of an X509 V3 certificate in DER/ASN.1 format.
    In addition, the certificate should contain only the public key of the public/private key pair. Using the - l option, the administrator should invoke the pdm_pki utility to load the certificate. The utility then loads the certificate, extracts the public key, converts the public key to BASE64 text format, and saves it with the access policy specified by the policy code.
    When a digital certificate is generated by the pdm_pki utility, the administrator invokes the command in CA SDM without the - l option. The utility then generates a public and private key pair (keys are RSA1024 bit keys). The public key is converted to BASE64 text format where it is stored along with the access policy specified by the policy code. An X509 V3 certificate is also created to hold the public key along with other information (the default pass phase is set as the policy code). Finally, the X509 V3 certificate is packaged with the private key to a standard portable certificate format of PKCS12. It is then saved in a file with a file name of
    policy_code
    .p12, depending on the policy code supplied. This file can then be exported to clients.
    If an access policy has already been associated with a public key of a certificate, users need to specify the - f option when calling the pdm_pki command in order to overwrite the existing public key with a new public key.
Login to Web Services
The following describes the process flow for logging in to Web Services configured with PKI authentication:
Process
Description
Load the Digital Certificate and Extract the Private Key
The digital certificate must be stored in secure storage on the user side, where it can be retrieved and used for logging in to Web Services.
Example of secure storages include the following:
Windows Certificate Store
Java Certificate Store (managed by java_keytool utility)
Certificate store (created by other CA Technologies security products).
A user application should be able to load the digital certificate and extract the private key using appropriate APIs, depending on user environments.
Create a Digital Signature of the Plain Text Policy Code with the Private Key
After the private key is extracted from the digital certificate, it can be used to generate a digital signature of policy code. Creating a digital signature encrypts a digest of a text with a private key. The digest algorithm must be standard SHA1, and the encryption algorithm should be RSA. Also, the binary digital signature should be converted to BASE64 text format before it can be used for logging in to Web Services. Depending on user environments, appropriate API calls should be used to archive this information.
Invoke the Web Service Call
A user application should invoke the Web Services method loginServiceManaged(), along with the plain text policy code and the BASE64 text formatted digital signature of the policy code.
Obtain the Returned SID
If the access request is authenticated, a plain text SID is automatically returned.
After a SID is generated, it establishes a successful binding between a Web Service session and an access policy. The user application can invoke other web services methods with this SID, and all of its access to Web Services becomes controlled and managed by this access policy.