com.rsa.certj.provider.pki

Class CRS

java.lang.Object
  |
  +--com.rsa.certj.Provider
        |
        +--com.rsa.certj.provider.pki.CRS

All Implemented Interfaces:

PKIDebug

Direct Known Subclasses:

CRSDebug

public class CRS

extends Provider

implements PKIDebug

This class provides the necessary functionality to send certificate requests to and receive certificate responses from a Certification Authority (CA) that uses the Certificate Request Syntax (CRS). Information needed to construct a complete CRS certificate request may be found in the VeriSign CRS Profile Specification, available from VeriSign. Because the options for creating certificate requests are many, this document details the options and combinations of data that are used to format a certificate request. In particular, read the sections of the specification regarding the content of regInfo strings carefully.

CRS-Based Protocol

At the highest level, the CRS certification request system uses a protocol called the Certificate Request Syntax. It uses unsecured HTTP to deliver PKCS #7-encapsulated messages between a client and a server. The protocol uses the signing and enveloping functionality defined by PKCS #7 to guarantee message integrity and privacy, respectively. This paradigm contrasts with a protocol that delivers cleartext messages over a secured data channel such as HTTPS to achieve the same result. This service provider implements both signed-only and enveloped-then-signed messages to ensure integrity and/or privacy. The recommendation is to use the enveloped-then-signed option to protect requests and responses; otherwise, all information, including cleartext passphrases, is subject to snooping and attack.

This service provider includes several features of the CRS protocol that are transparent to the application developer. In particular, this provider implements nonces in order to prevent playback attacks, as described in the CRS specification. This protection is transparent to the developer and the nonce-mismatch errors that occur in the event of attack should never occur in normal circumstances.

In addition, this service provider generates transaction identifiers automatically, unless they are specified explicitly. These transaction identifiers are generated according to the algorithm recommended in the CRS specification.

This service provider does not verify that the signer of a CRS response is the expected sender. However, the sender field in the message represents the actual signer of the message, so you can and should verify that the actual signer is the expected sender.

Certificate Request and Response Messages

To use this provider successfully, set certain fields correctly; other fields are unused by this provider. The following overview describes each of the fields, and how they can or must be set, to produce a successful certification request; it also explains how they can be used to interpret a certification response.

The PKIMessage class, which is used by both certification requests and responses, includes the following fields:

• The sender field of the PKIMessage class must be set to perform message signing with a CRS Registration Authority (RA) certificate. To sign the message with the end-entity key rather than with the RA key, set this field to null.
  This field holds a PKCS #7-defined SignerInfo object with a number of subfields:

  • For certification request messages, only the certificate identifier (the issuer name and serial number), the signature algorithm, and the digest algorithm fields are used. Do not use the authenticated attributes and unauthenticated attributes fields; the service provider uses them to build request-related attributes that are necessary for the protocol.

  • For certification response messages, all subfields of sender are significant.
    Note: This service provider does not verify that the signer of a CRS response is the expected sender. However, the sender field in the message represents the actual signer of the message, so you can and should verify that the actual signer is the entity that you expected to sign the response.

• The recipient field of the PKIMessage class must be valid so that messages can be enveloped. This field holds a PKCS #7-defined RecipientInfo object. It is used to identify the certificate that contains the public key of the intended CRS Autoresponder.
  Enveloped messages are strongly recommended if a certification request contains registration information that should be protected from snooping. Otherwise, the use of enveloping is at the discretion of the application developer.

• The version field of the PKIMessage class does not need to be set by the application. The service provider will set this field appropriately when the request is composed and when a response is received.

• The transactionID field of the PKIMessage class is used to associate requests with responses. If this field is null, the service provider automatically generates a transaction ID that complies with the CRS specification.

• The extraCerts and extraCRLs fields of the PKIMessage class serve functions specific to the message type:
  • For certification request messages, the extraCerts field holds the self-signed certificate when it is necessary for the provider to generate one.

  • For certification response messages, these fields may contain other information necessary to construct a certificate chain that corresponds to the issued certificate.

• The messageTime and freeText fields of the PKIMessage class are not used by this service provider.

Preparing a Certification Request

In addition to the PKIMessage fields described above, a certification request object contains the following PKIRequestMessage fields:

• The certificateTemplate field of the PKIRequestMessage class is used to set the characteristics of the certificate to be issued. Correct and complete use of this field is critical to the success of the certification request.

• The popType field of the PKIRequestMessage class does not need to be set, because PKIRequestMessage.PKI_POP_SIGNATURE is the only proof-of-possession that this service provider can use. The provider will set this automatically.

• The regInfo field of the PKIRequestMessage class is implicitly required by the service provider, because every type of certification request uses this field. The contents of this field depend on the certificate issuance particulars, so it is necessary to have CRS-specific knowledge of the requirements.

Proof-of-Possession

The popGenerationInfo parameter to PKIService.generateProofOfPossession is unnecessary for this provider and should be set to null.

The PKIInterface.validateProofOfPossession SPI method is not used by this provider. After the CA processes the certification request, it returns status information and, if successful, a certificate. In addition to the PKIMessage fields described above, the certification response object will contain the following PKIResponseMessage fields:

• The statusInfo field of the PKIResponseMessage class will contain a PKIStatusInfo object with four data items:
  1. The status field indicates the overall status of the PKI operation.
  2. The failInfo field will always contain additional status information if status is not equal to PKIStatusInfo.PKI_STATUS_GRANTED (0).
  3. The statusStrings field will hold the HTTP headers returned. If any type of error occurred, the body of the message will be added to the statusStrings, after the HTTP headers with null as the delimiter.
  4. The failInfoAux field will contain the exact error value returned by the CRS autoresponder. Descriptions of these values can be found in the VeriSign CRS Profile Specification.

• The regInfo field of the PKIResponseMessage class will contain the same regInfo information that was provided in the corresponding certification request, if the CRS autoresponder was sufficiently successful in parsing the request.

• The certificate field of the PKIResponseMessage class will contain the requested certificate, if the request is successful. Any additional certificates may be found in the extraCerts field of PKIMessage in the response object.

• The caCerts field of the PKIResponseMessage class is always ignored by this service provider.

Establishing a Protection Context

To sign or envelope messages or receive signed or enveloped messages, it is necessary to establish a protection context for the service provider. A ProtectInfo object is passed into some of the SPI methods for this provider. This service provider, specifically, uses the certPathCtx field of ProtectionInfoPublicKey to compose and decompose signed or enveloped messages. This protection context is composed with the following components:

• One or more databases from which to retrieve one's own private signing and encryption keys, and the public signing and encryption keys of those from whom you receive messages, as well as any intermediate certificates which are needed to perform chain validation.

• A list of trusted certificates that correspond to the root of the trust chain for the OnSite service.

• A method by which to perform path validation and a corresponding set of flags.

Copyright © RSA Security Inc., 1999-2001. All rights reserved.

Field Summary

static int

POP_TYPE_CSR Indicates that it uses Certificate Signing Request (CSR) when providing proof-of-possession.

Constructor Summary

CRS(String name, File configFile)

Constructs a CRS object, using a configFile that is given as a File.

CRS(String name, InputStream configStream)

Constructs a CRS object, using a configStream that is given as an InputStream.

CRS(String name, String configFileName)

Constructs a CRS object using a configFileName that is given as a String.

Method Summary

ProviderImplementation	instantiate(CertJ certJ) Creates a ProviderImplementation object that handles CRS PKI SPI methods.
void	saveCertificate(PKIResponseMessage response) Does not do anything.
void	saveData(byte[] data, String fileName) Does not do anything.
void	saveMessage(byte[] bytes, PKIMessage message, ProtectInfo protectInfo) Does not do anything.

Methods inherited from class com.rsa.certj.Provider

getName, getType

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

POP_TYPE_CSR

public static final int POP_TYPE_CSR

Indicates that it uses Certificate Signing Request (CSR) when providing proof-of-possession.

Constructor Detail

CRS

public CRS(String name,
           InputStream configStream)
    throws InvalidParameterException

Constructs a CRS object, using a configStream that is given as an InputStream.

Parameters

	name		A String specifying the name of this provider.
	configStream		An InputStream indicating the input stream that obtains the configuration information for this provider instance. The contents of the resource pointed to by configStream are "properties-style" lines of text. The property names which this provider recognizes are dest, http.proxy, profile, and timeoutSecs. dest specifies the location(s) of the OnSite CRS auto-responder(s). http.proxy specifies the hostname:port of any HTTP proxies which may exist between the application and the CRS auto-responder. profile specifies the particular CRS profile that is implemented by the responder, in anticipation that there may be subtle differences. The current implementation of this service provider has only been tested with the VeriSign OnSite responder, and its profile name has been chosen to be VeriSign. If this optional entry is left unspecified, it will default to VeriSign. timeoutSecs specifies how many seconds the application should wait before giving up on socket communication. For example, the contents of the configuration file might be: dest=http://onsite-admin.verisign.com/cgi-bin/crs.exe http.proxy=proxy1.mycompany.com:80 http.proxy=proxy2.mycompany.com:80 profile=VeriSign timoutSecs=20

Throws

InvalidParameterException - If any argument is invalid.

CRS

public CRS(String name,
           File configFile)
    throws InvalidParameterException

Constructs a CRS object, using a configFile that is given as a File.

Parameters

	name		A String specifying the name of this provider.
	configFile		A File indicating the name of the file that contains the configuration information for this provider instance. The contents of the resource pointed to by configFile are "properties-style" lines of text. The property names which this provider recognizes are dest, http.proxy, profile, and timeoutSecs. dest specifies the location(s) of the OnSite CRS auto-responder(s). http.proxy specifies the hostname:port of any HTTP proxies which may exist between the application and the CRS auto-responder. profile specifies the particular CRS profile that is implemented by the responder, in anticipation that there may be subtle differences. The current implementation of this service provider has only been tested with the VeriSign OnSite responder, and its profile name has been chosen to be VeriSign. If this optional entry is left unspecified, it will default to VeriSign. timeoutSecs specifies how many seconds the application should wait before giving up on socket communication. For example, the contents of the configuration file might be: dest=http://onsite-admin.verisign.com/cgi-bin/crs.exe http.proxy=proxy1.mycompany.com:80 http.proxy=proxy2.mycompany.com:80 profile=VeriSign timoutSecs=3

Throws

InvalidParameterException - If any argument is invalid.

CRS

public CRS(String name,
           String configFileName)
    throws InvalidParameterException

Constructs a CRS object using a configFileName that is given as a String.

Parameters

	name		A String specifying the name of this provider.
	configFileName		A File indicating the name of the file that contains the configuration information for this provider instance. The contents of the resource pointed to by configFileName are "properties-style" lines of text. The property names which this provider recognizes are dest, http.proxy, profile, and timeoutSecs. dest specifies the location(s) of the OnSite CRS auto-responder(s). http.proxy specifies the hostname:port of any HTTP proxies which may exist between the application and the CRS auto-responder. profile specifies the particular CRS profile that is implemented by the responder, in anticipation that there may be subtle differences. The current implementation of this service provider has only been tested with the VeriSign OnSite responder, and its profile name has been chosen to be VeriSign. If this optional entry is left unspecified, it will default to VeriSign. timeoutSecs specifies how many seconds the application should wait before giving up on socket communication. For example, the contents of the configuration file might be: dest=http://onsite-admin.verisign.com/cgi-bin/crs.exe http.proxy=proxy1.mycompany.com:80 http.proxy=proxy2.mycompany.com:80 profile=VeriSign timeoutSecs=3

Throws

InvalidParameterException - If any argument is invalid.

Method Detail

instantiate

public ProviderImplementation instantiate(CertJ certJ)
                                   throws ProviderManagementException

Creates a ProviderImplementation object that handles CRS PKI SPI methods. This method is called by CertJ.registerService when an object of the CRS class is being registered. Applications do not have to call this method.

Overrides

instantiate in class Provider

Parameters

certJ

A CertJ object for which the created provider is registered.

Returns

A ProviderImplementation object that provides the SPI implementations for CRS PKI providers.

Throws

ProviderManagementException - If instantiation of the CRS PKI provider fails.

saveMessage

public void saveMessage(byte[] bytes,
                        PKIMessage message,
                        ProtectInfo protectInfo)
                 throws PKIException

Does not do anything. It is a place holder for a subclass of this class that is provided by this method for debugging purposes.

Specified by:

saveMessage in interface PKIDebug

Parameters

	bytes		A byte array that contains a serialized request or response message to be saved.
	message		A PKIMessage object contains information that corresponds to the serialized message.
	protectInfo		A ProtectInfo object used to generate protection bites for the serialized message.

Throws

PKIException - If saving the message fails.

saveCertificate

public void saveCertificate(PKIResponseMessage response)
                     throws PKIException

Does not do anything. It is a place holder for a subclass of this class that provide this method for debugging purposes.

Specified by:

saveCertificate in interface PKIDebug

Parameters

response

A PKIResponseMessage object with which a certificate may have returned.

Throws

PKIException - If saving the certificate returned fails.

saveData

public void saveData(byte[] data,
                     String fileName)
              throws PKIException

Does not do anything. It is a place holder for a subclass of this class that is provided by this method for debugging purposes.

Specified by:

saveData in interface PKIDebug

Parameters

	data		A byte array to be stored into a file.
	fileName		A String object indicating the name of the file where the data is stored.

Throws

PKIException - If saving the data fails.