com.rsa.certj

Class PKIService

java.lang.Object
  |
  +--com.rsa.certj.Service
        |
        +--com.rsa.certj.PKIService

public final class PKIService

extends Service

This class represents a PKI service. All the PKI APIs, such as sendRequest, are defined as methods for this class. Create an object of this class to perform PKI operations. The bindService method of the CertJ class creates an object of this class.

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

See Also

CertJ.bindService(int, java.lang.String)

Constructor Summary

PKIService(CertJ certJ)

Constructs a PKIService object for certJ.

Method Summary

void	generateProofOfPossession(PKIRequestMessage request, com.rsa.jsafe.JSAFE_PrivateKey privateKey, POPGenerationInfo popGenerationInfo) Generates a proof-of-possession (POP) for the indicated private key and attaches it to the message object.
void	provideProofOfPossession(PKIRequestMessage request, int popType, byte[] pop) Provides proof-of-possession for certificate requests for entities that do not provide direct access to the private key to be certified.
PKIResponseMessage	readCertificationResponseMessage(byte[] response, ProtectInfo protectInfo) Deprecated. Use the sendRequest method instead of this method.
PKIResponseMessage	requestCertification(PKIRequestMessage request, ProtectInfo protectInfo, DatabaseService db) Deprecated. Use the sendRequest method instead of this method.
PKIResult	sendMessage(byte[] request) Sends a serialized request message (for example, as returned by writeCertificationRequestMessage) to the specified PKI service provider.
PKIResponseMessage	sendRequest(PKIRequestMessage request, ProtectInfo protectInfo, DatabaseService db) Sends a request message to the specified PKI service provider.
boolean	validateProofOfPossession(PKIMessage message, POPValidationInfo popValidationInfo) Validates a proof-of-possession.
byte[]	writeCertificationRequestMessage(PKIRequestMessage request, ProtectInfo protectInfo) Deprecated. Use the sendRequest method instead of this method.

Methods inherited from class com.rsa.certj.Service

getInstance, listProviderNames, toString, unbind

Methods inherited from class java.lang.Object

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

Constructor Detail

PKIService

public PKIService(CertJ certJ)

Constructs a PKIService object for certJ.

Parameters

certJ

The CertJ that represents the current CertJ object.

Method Detail

readCertificationResponseMessage

public PKIResponseMessage readCertificationResponseMessage(byte[] response,
                                                           ProtectInfo protectInfo)
                                                    throws InvalidParameterException,
                                                           NoServiceException,
                                                           PKIException

Deprecated. Use the sendRequest method instead of this method.

Processes a certification response message.

Parameters

	response		A byte array that contains the serialized response message to process.
	protectInfo		A ProtectInfo object that holds information used to validate a message cryptographically or to unprotect the message.

Returns

A PKIResponseMessage that contains information extracted from response.

Throws

InvalidParameterException - If the response argument is null.

NoServiceException - If the service provider does not provide readCertificationResponseMessage service.

PKIException - If the PKI service provider fails.

See Also

sendRequest(com.rsa.certj.spi.pki.PKIRequestMessage, com.rsa.certj.spi.pki.ProtectInfo, com.rsa.certj.DatabaseService)

writeCertificationRequestMessage

public byte[] writeCertificationRequestMessage(PKIRequestMessage request,
                                               ProtectInfo protectInfo)
                                        throws InvalidParameterException,
                                               NoServiceException,
                                               PKIException

Deprecated. Use the sendRequest method instead of this method.

Creates a serialized certification request message according to the protocol implemented by the specified PKI service provider.

Parameters

	request		A PKIRequestMessage object that contains the certification request message.
	protectInfo		A ProtectInfo object holding information used to validate the message cryptographically or to unprotect the message.

Returns

A byte array that contains the serialized request message.

Throws

InvalidParameterException - If the request argument is null, or the protectInfo argument is null.

NoServiceException - If the service provider does not provide a writeCertificationRequestMessage service.

PKIException - If the PKI service provider fails.

See Also

sendRequest(com.rsa.certj.spi.pki.PKIRequestMessage, com.rsa.certj.spi.pki.ProtectInfo, com.rsa.certj.DatabaseService)

requestCertification

public PKIResponseMessage requestCertification(PKIRequestMessage request,
                                               ProtectInfo protectInfo,
                                               DatabaseService db)
                                        throws InvalidParameterException,
                                               NoServiceException,
                                               PKIException

Deprecated. Use the sendRequest method instead of this method.

Sends a certification request message to the specified PKI service provider. The PKI service provider receives and processes the response. If any certificates, CRLs, or keys are received in the response, they are stored in the database service specified by db. The PKI-client application can examine the response message for status information. In addition, some PKI service providers might require the PKI-client application to examine the response to determine whether the identity of the responder is the one expected by the PKI-client application. (For example, if the response message was protected with a digital signature, the PKI-client application might need to verify that the subject name of the signing certificate is the same as the expected responder name.)

Parameters

	request		A PKIRequestMessage object that contains the certification request message.
	protectInfo		A ProtectInfo object holding information used to generate cryptographic protection for the request message.
	db		A DatabaseService object indicating where keys, certificates, and CRLs from the response message are to be stored. Note that not all service providers return keys, certificates, and CRLs in the response.

Returns

A PKIResponseMessage object that contains a response message corresponding to the certification request message. You can expect the service provider to fill in at least the statusInfo field of the PKIResponseMessage.

Throws

InvalidParameterException - If the request argument is null.

NoServiceException - If the service provider does not provide a requestCertification service.

PKIException - If the PKI service provider fails.

See Also

sendRequest(com.rsa.certj.spi.pki.PKIRequestMessage, com.rsa.certj.spi.pki.ProtectInfo, com.rsa.certj.DatabaseService)

sendRequest

public PKIResponseMessage sendRequest(PKIRequestMessage request,
                                      ProtectInfo protectInfo,
                                      DatabaseService db)
                               throws InvalidParameterException,
                                      NoServiceException,
                                      PKIException

Sends a request message to the specified PKI service provider. The PKI service provider receives and processes the response. If any certificates, CRLs, or keys are received in the response, they are stored in the database service specified by db. Your PKI-client application can examine the response message for status information. In addition, some PKI service providers might require the PKI-client application to examine the response to determine whether the identity of the responder is the one expected by the PKI-client application. (For example, if the response message was protected with a digital signature, the PKI-client application might need to verify that the subject name of the signing certificate is the same as the expected responder name.)

Parameters

	request		A PKIRequestMessage object that contains the request message.
	protectInfo		A ProtectInfo object holding information used to generate cryptographic protection for the request message.
	db		A DatabaseService object indicating where keys, certificates, and CRLs from the response message are to be stored. Note that not all service providers return keys, certificates, and CRLs in the response.

Returns

A PKIResponseMessage object that contains a response message corresponding to the certification request message. You can expect the service provider to fill in at least the statusInfo field of the PKIResponseMessage.

Throws

InvalidParameterException - If the request argument is null.

NoServiceException - If the service provider does not provide a requestCertification service.

PKIException - If the PKI service provider fails.

sendMessage

public PKIResult sendMessage(byte[] request)
                      throws InvalidParameterException,
                             NoServiceException,
                             PKIException

Sends a serialized request message (for example, as returned by writeCertificationRequestMessage) to the specified PKI service provider. The serialized response is returned to your PKI-client application. Your PKI-client application can read the response into a PKIResponseMessage object using a readMessage method (for example, readCertificationResponseMessage).

Parameters

request

A byte array that contains a serialized request message.

Returns

A PKIResult object that contains status information about sending the request and the serialized response message received.

Throws

InvalidParameterException - If request argument is null.

NoServiceException - If it does not provide sendMessage service.

PKIException - If the PKI service provider fails.

generateProofOfPossession

public void generateProofOfPossession(PKIRequestMessage request,
                                      com.rsa.jsafe.JSAFE_PrivateKey privateKey,
                                      POPGenerationInfo popGenerationInfo)
                               throws InvalidParameterException,
                                      NoServiceException,
                                      PKIException

Generates a proof-of-possession (POP) for the indicated private key and attaches it to the message object. Proof-of-possession means the proof of possessing the private key, such as signature bits generated using the corresponding private key. (In some cases, the service provider can defer actual production of the proof-of-possession until the entire message is serialized and instead attach necessary precursor data to the message object at the time this function is called. Call this function after initializing the relevant fields of the certification request object, but before sending the request to the PKI service provider.

Parameters

	request		A PKIRequestMessage object that contains a certification request message.
	privateKey		A JSAFE_PrivateKey object with proven possession.
	popGenerationInfo		A POPGenerationInfo object that contains information used to generate the proof-of-possesion.

Throws

InvalidParameterException - If the request argument is null.

NoServiceException - If the service provider does not provide a generateProofOfPossession service.

PKIException - If the PKI service provider fails.

validateProofOfPossession

public boolean validateProofOfPossession(PKIMessage message,
                                         POPValidationInfo popValidationInfo)
                                  throws InvalidParameterException,
                                         NoServiceException,
                                         PKIException

Validates a proof-of-possession. This method can be used in one of two ways:

1. A PKI server can use this method to validate the proof-of-possession of a private key contained in a certification request message. In this case, message would contain the certification request. If the proof-of-possession is performed by transmitting the subject's private key to the PKI service provider, a private key object that contains the relevant information will be returned. If the message does not contain a copy of the private key, no private key will be returned.

2. The end-entity (PKI client) application can use this method to do any necessary client-side steps in the proof-of-possession method selected. In this case, message would contain the certification response. For example, if the POP type is PKI_POP_ENCRYPTION and the POP method is POP_METHOD_ENCRYPT_CERT, the application can retrieve its certificate by supplying the corresponding private key. The service provider would update the message object with a decrypted copy of the certificate. (The service provider can also send a confirmation message to the PKI service provider.) If the PKI service provider generates the private key on behalf of the end entity, the certification response message can contain the private key.

Some PKI service providers might support only one of the two preceding usage models. The popValidationInfo parameter, along with other data contained in the message object (for example, the subject public key for a signature key certificate), is used to do any necessary decryption or validation operations on the POP contained in the message object.

Parameters

	message		A PKIMessage object that contains the public key that needs proof-of-possession validation.
	popValidationInfo		A POPValidationInfo object that contains information required to validate the POP (and potentially retrieve the accompanying private key).

Returns

true if the proof-of-possession is validated, false otherwise.

Throws

InvalidParameterException - If the message argument is null.

NoServiceException - If the service provider does not provide validateProofOfPossession service.

PKIException - If the PKI service provider fails.

provideProofOfPossession

public void provideProofOfPossession(PKIRequestMessage request,
                                     int popType,
                                     byte[] pop)
                              throws InvalidParameterException,
                                     NoServiceException,
                                     PKIException

Provides proof-of-possession for certificate requests for entities that do not provide direct access to the private key to be certified. Examples of such entities are secure Web servers, routers, and IPSec firewalls.

Parameters

	request		A PKIRequestMessage object that contains a certification request message.
	popType		An int indicating the format of pop, which is service-provider-specific.
	pop		A byte array holding the proof-of-possession to use.

Throws

InvalidParameterException - If the request argument is null.

NoServiceException - If the service provider does not provide provideProofOfPossession service.

PKIException - If the PKI service provider fails.