com.rsa.certj.spi.pki

Interface PKIInterface

public interface PKIInterface

This interface specifies PKI Service Provider Programming Interface (SPI) methods, such as sendRequest, that can be implemented by a PKI service provider.

A PKI service provider may implement some or all of the methods in the PKI SPI. If an application invokes a PKI method or uses an argument that is not supported by the PKI service provider, Cert-J will throw an exception.

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

Method Summary

void	generateProofOfPossession(PKIRequestMessage request, com.rsa.jsafe.JSAFE_PrivateKey privateKey, POPGenerationInfo popGenerationInfo) Generates a Proof-of-Possession of the indicated private key and attaches it to the message object.
void	provideProofOfPossession(PKIRequestMessage message, int popType, byte[] pop) Provides a Proof-of-Possession for certificate requests from entities which do not provide direct access to the private key to certify.
PKIResponseMessage	readCertificationResponseMessage(byte[] response, ProtectInfo protectInfo) Deprecated. Use sendRequest.
PKIResponseMessage	requestCertification(PKIRequestMessage request, ProtectInfo protectInfo, DatabaseService db) Deprecated. Replaced by sendRequest.
PKIResult	sendMessage(byte[] request) Deprecated. Use sendRequest.
PKIResponseMessage	sendRequest(PKIRequestMessage request, ProtectInfo protectInfo, DatabaseService db) Sends a request message to the specified PKI service, which receives and processes the request, and returns a response message.
boolean	validateProofOfPossession(PKIMessage message, POPValidationInfo popValidationInfo) Validates a Proof-of-Possession.
byte[]	writeCertificationRequestMessage(PKIRequestMessage request, ProtectInfo protectInfo) Deprecated. Use sendRequest.

Method Detail

readCertificationResponseMessage

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

Deprecated. Use sendRequest.

Processes a certification response message.

The application is responsible for the long-term disposition of the information. This method does not store any elements of the certification response in persistent datastores.

Parameters

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

Returns

A PKIResponseMessage that contains information extracted from the response message.

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

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 NotSupportedException,
                                               PKIException

Deprecated. Use sendRequest.

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

Parameters

	request		A PKIRequestMessage that contains a certification request message object.
	protectInfo		A ProtectInfo object that contains information used to protect the message cryptographically.

Returns

A byte array that contains a serialized request message.

Throws

NotSupportedException - If this provider does not support this method for a given set of arguments.

PKIException - If there is some unrecoverable error in the PKI operations.

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 NotSupportedException,
                                               PKIException

Deprecated. Replaced by sendRequest.

Sends a certification request message to the specified PKI service, which receives the request, processes it, and returns a response message. If any certificates, CRLs, or keys are received in the response, these are stored in the indicated database services.

The application can examine the response message for status information. In addition, some services may require examination of the response to determine whether the identity of the responder is the one that the application expects. For example, if the response message was protected with a digital signature, the application may 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 a certification request message object.
	protectInfo		A ProtectInfo object that contains 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 services return keys, certificates, and CRLs in the response.

Returns

A PKIResponseMessage object corresponding to the certification request message. The application can expect the service provider to fill in at least the statusInfo field of the PKIResponseMessage associated with the response object.

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

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 NotSupportedException,
                                      PKIException

Sends a request message to the specified PKI service, which receives and processes the request, and returns a response message. If any certificates, CRLs, or keys are received in the response, these are stored in the indicated database services.

The application can examine the response message for status information. In addition, some services may require examination of the response to determine whether the identity of the responder is the one that the application expects. For example, if the response message was protected with a digital signature, the application may 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 a request message object.
	protectInfo		A ProtectInfo object that contains 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 services return keys, certificates, and CRLs in the response.

Returns

A PKIResponseMessage object corresponding to the request message. The application can expect the service provider to fill in at least the statusInfo field of the PKIResponseMessage associated with the response object.

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

sendMessage

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

Deprecated. Use sendRequest.

Sends a serialized request message (for example, as returned by writeCertificationRequestMessage) to the specified PKI service. The serialized response is returned to the application. The application can read the response into a PKIResponseMessage using any of the read*Message methods, such as readCertificationResponseMessage.

Parameters

request

A byte array that contains the serialized request message.

Returns

A PKIResult object that contains a serialized response message and out-of-band status information.

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

See Also

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

generateProofOfPossession

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

Generates a Proof-of-Possession of the indicated private key and attaches it to the message object. (In some cases the service provider may defer actual production of the POP until the entire message is serialized and instead attach necessary precursor data to the message object at the time this method is called.) The application should call this method after initializing the relevant fields of the certification request object, but before sending the request to the PKI service.

Parameters

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

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

validateProofOfPossession

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

Validates a Proof-of-Possession. This function 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 contains the certification request.
   If the Proof-of-Possession is performed by transmitting the subject's private key to the PKI server, 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 contains the certification response.
   For example, if the POP type is PKI_POP_ENCRYPTION and the POP method used is encrypting the certificate, 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 may send a confirmation message to the PKI server, but that would be a side effect.)
   If the PKI server generates the private key on behalf of the end-entity, the certification response message could contain the private key.

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.

Note: Some PKI service providers may support only one of the two preceding usage models.

Parameters

	message		A PKIMessage object that contains the public key whose possession is to be proven.
	popValidationInfo		A POPValidationInfo that contains information required to validate the POP and potentially to retrieve the accompanying private key.

Returns

A boolean indicating the result of validation.

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.

provideProofOfPossession

public void provideProofOfPossession(PKIRequestMessage message,
                                     int popType,
                                     byte[] pop)
                              throws NotSupportedException,
                                     PKIException

Provides a Proof-of-Possession for certificate requests from entities which do not provide direct access to the private key to certify. Example of such entities are secure Web servers, routers and IPSec firewalls.

Parameters

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

Throws

NotSupportedException - If the provider does not support this method for the given set of arguments.

PKIException - If there is an unrecoverable error in any PKI operation.