com.ls.security.pki
Interface IPKIUtil


public interface IPKIUtil

IPKIUtil is a utility interface for Public Key Infrastructure (PKI) functionalities. The main PKI functionalities are:

 1. Decrypt a message
 2. Encrypt a message
 3. Verify the digital signature in the message
 4. Retrieve and verify the Certificate
 5. Generate key pairs
 6. Generate PKCS#10 Certificate Request
 7. Send request to the specified Web Gateway
 

Version:
$Revision: 1.4 $
Author:
Last modified by $Author: JBogenschuetz $

Method Summary
 void checkTheValidityOfCachedCertificate(byte[] oneCachedCertificate)
          Takes a byte array representation of a certificate, and checks it agains the current date.
 String decryptMessage(String encryptedText, Object privateKey)
          decrypts a text
 String decryptMessage(String encryptedText, String privateKeyFileName, String directoryName, String password)
          decrypts a text
 String encryptMessage(String originalText, byte[] certificate)
          encrypts a text
 String encryptMessage(String originalText, Object publicKey)
          encrypts a text
 String encryptMessage(String originalText, String certificateFileName, String directoryName)
          encrypts a text
 void generateKeyPairs(String location, String password, String randomString)
          Uses "RSA" algorithm and generates the private key (private_key.p12, PKCS#8 encoded), and public key (public_key.p12) and saves it in the directory specified in the parameter.
 void generateKeyPairs(String location, String nameForKeyFiles, String password, String randomString)
          Uses "RSA" algorithm and generates the private key (private_key.p12, PKCS#8 encoded), and public key (public_key.p12) and saves it in the directory specified in the parameter.
 Object generatePKCS10Request(String keyLocation, String privateKeyFileName, String publicKeyFileName, String privateKeyPassword, Map userData)
          Generates and requests the PKCS#10-certificate.
 String generateSignature(String originalText, Object rsaPrivateKey)
          signs a text
 String generateSignature(String originalText, String privateKeyFileName, String directoryName, String password)
          signs a text
 ArrayList getInvalidPublicKeyCertificates(HashMap thePublicKeyCertificateCache)
          Gets the list of keys whose certificates are no longer valid.
 Date getNextCRLUpdateDate()
          returns the date of next CRL update.
 byte[] getPKICertificate(Map userData)
          Gets a certificate of a user.
 Object getPrivateKey(String privateKeyFileName, String directoryName, String password)
          Loads the given private key file by using the given password and path.
 byte[] getPublicKeyCertificate(String certificateFileName, String directoryName)
          Loads the given certificateFileName file by using the given path.
 void sendCertificateRequestToRA(Object theCertificateRequest, Map publicCertificateRequestParameters)
          Generates the PKCS#10 request by using the given user data, and sends the certificate request to the given WebGateway.
 void setPublicPKIServer(Map publicPKIServerParameters)
          Sets the parameters to get certificates/public keys from a public PKI Server.
 void verifySignature(String signature, String signedData, byte[] certificate)
          verifies signature
 void verifySignature(String signature, String signedData, String certificateFileName, String directoryName)
          verifies signature
 

Method Detail

generateKeyPairs

public void generateKeyPairs(String location,
                             String password,
                             String randomString)
                      throws PKIBaseException
Uses "RSA" algorithm and generates the private key (private_key.p12, PKCS#8 encoded), and public key (public_key.p12) and saves it in the directory specified in the parameter.
Parameters:
location - directory name where the file has to be stored. It should be ended with backslash or forward slash
password - password to protect the private key file
randomString - random seed to generate the secure random. It can be obtained from the random mouse event
Throws:
PKIBaseException - If a PKI-error occurs

generateKeyPairs

public void generateKeyPairs(String location,
                             String nameForKeyFiles,
                             String password,
                             String randomString)
                      throws PKIBaseException
Uses "RSA" algorithm and generates the private key (private_key.p12, PKCS#8 encoded), and public key (public_key.p12) and saves it in the directory specified in the parameter.
Parameters:
location - directory name where the file has to be stored. It should be ended with backslash or forward slash
nameForKeyFiles - by providing this String, the key file can be saved by using this name, for example, if providing "FirstName_LastName_UserName", the private key file can be saved in "FirstName_LastName_UserName_private_key.p12". If this value is null, it will be saved as "private_key.p12" by default.
password - password to protect the private key file
randomString - random seed to generate the secure random. It can be obtained from the random mouse event
Throws:
PKIBaseException - If a PKI-error occurs

generatePKCS10Request

public Object generatePKCS10Request(String keyLocation,
                                    String privateKeyFileName,
                                    String publicKeyFileName,
                                    String privateKeyPassword,
                                    Map userData)
                             throws PKIBaseException,
                                    IllegalArgumentException
Generates and requests the PKCS#10-certificate. The request is sent to the public PKI-Server.
Parameters:
keyLocation - Location of the private and public keys
privateKeyFileName - file name of the private key
publicKeyFileName - file name of the public key
privateKeyPassword - password to the private key
userData - contains the needed userData to specify the user. For instance CN=John Smith,OU=Development,O=Living Systems,C=DE.
Returns:
JCRYPTO_X509CertRequest object
Throws:
PKIBaseException - If a PKI-error occurs
IllegalArgumentException - If there are invalid arguments

sendCertificateRequestToRA

public void sendCertificateRequestToRA(Object theCertificateRequest,
                                       Map publicCertificateRequestParameters)
                                throws PKIBaseException,
                                       IllegalArgumentException
Generates the PKCS#10 request by using the given user data, and sends the certificate request to the given WebGateway. The private key file must be in PKCS#12 format
Parameters:
theCertificateRequest - certificate request object to send to Public PKI Server
publicCertificateRequestParameters - Map which contains the certificate request parameters
Throws:
PKIBaseException - If IO errors, password error, algorithms error, and encoding errors happen
IllegalArgumentException - If there are invalid arguments

generateSignature

public String generateSignature(String originalText,
                                String privateKeyFileName,
                                String directoryName,
                                String password)
                         throws PKIBaseException
signs a text
Parameters:
originalText - original text to sign (as String)
privateKeyFileName - file name of one's private key
directoryName - directory name where the private key file resides.
password - password to activate one's private key
Returns:
generated Signature
Throws:
PKIBaseException - If a PKI-error occurs

generateSignature

public String generateSignature(String originalText,
                                Object rsaPrivateKey)
                         throws PKIBaseException
signs a text
Parameters:
originalText - original text to sign (as String)
rsaPrivateKey - private key used to sign the original String
Returns:
generated Signature
Throws:
PKIBaseException - If a PKI-error occurs

verifySignature

public void verifySignature(String signature,
                            String signedData,
                            String certificateFileName,
                            String directoryName)
                     throws PKIBaseException
verifies signature
Parameters:
signature - signature as String
signedData - signed (original) data as String
certificateFileName - file name of one's certificate (contains the public key)
directoryName - directory name where the certificate file resides.
Throws:
PKIBaseException - If a PKI-error occurs

verifySignature

public void verifySignature(String signature,
                            String signedData,
                            byte[] certificate)
                     throws PKIBaseException
verifies signature
Parameters:
signature - signature as String
signedData - signed (original) data as String
certificate - byte-array representation of the needed certificate
Throws:
PKIBaseException - If a PKI-error occurs

encryptMessage

public String encryptMessage(String originalText,
                             String certificateFileName,
                             String directoryName)
                      throws PKIBaseException
encrypts a text
Parameters:
originalText - string to encrypt
certificateFileName - file name of the receiver's certificate (contains the public key)
directoryName - directory name where the private key file resides.
Returns:
encrypted string
Throws:
PKIBaseException - If a PKI-error occurs

encryptMessage

public String encryptMessage(String originalText,
                             byte[] certificate)
                      throws PKIBaseException
encrypts a text
Parameters:
originalText - string to encrypt
certificate - byte-array representation of the needed certificate
Returns:
The encrypted string
Throws:
PKIBaseException - If a PKI-error occurs

encryptMessage

public String encryptMessage(String originalText,
                             Object publicKey)
                      throws PKIBaseException
encrypts a text
Parameters:
originalText - string to encrypt
publicKey - public key used to encrypt the decryted string
Returns:
The encrypted string
Throws:
PKIBaseException - If a PKI-error occurs

decryptMessage

public String decryptMessage(String encryptedText,
                             String privateKeyFileName,
                             String directoryName,
                             String password)
                      throws PKIBaseException
decrypts a text
Parameters:
encryptedText - string to decrypt
privateKeyFileName - file name of one's private key
directoryName - directory name where the private key file resides.
password - password to activate one's private key
Returns:
The decrypted string
Throws:
PKIBaseException - If a PKI-error occurs

decryptMessage

public String decryptMessage(String encryptedText,
                             Object privateKey)
                      throws PKIBaseException
decrypts a text
Parameters:
encryptedText - string to decrypt
privateKey - private key used to decrypt the encryted string
Returns:
decrypted string
Throws:
PKIBaseException - If a PKI-error occurs

getPrivateKey

public Object getPrivateKey(String privateKeyFileName,
                            String directoryName,
                            String password)
                     throws PKIBaseException
Loads the given private key file by using the given password and path. It unlocks the private key file and creates the PrivateKey object, which is returned as an Object.
Parameters:
privateKeyFileName - file name of the private key file.
directoryName - directory name where the private file is stored.
password - password which protects this private key file
Returns:
private key object
Throws:
PKIBaseException - If key file doesn't exist or its encoding is not correct or the password not correct

getPublicKeyCertificate

public byte[] getPublicKeyCertificate(String certificateFileName,
                                      String directoryName)
                               throws PKIBaseException
Loads the given certificateFileName file by using the given path. It creates the Certificate object, which is returned as byte array (PEM format).
Parameters:
certificateFileName - file name of the certificate file. (PEM format)
directoryName - directory name where the certificate file is stored.
Returns:
certificate object
Throws:
PKIBaseException - If certificate file doesn't exist or its encoding is not correct.

setPublicPKIServer

public void setPublicPKIServer(Map publicPKIServerParameters)
                        throws PKIBaseException,
                               IllegalArgumentException
Sets the parameters to get certificates/public keys from a public PKI Server.
Parameters:
publicPKIServerParameters - Map which contains the needed Parameters (needed parameters for Baltimore: String hostName, String port, String userNamePKIServer, String passwordPKIServer, String CACertificateFileName, String directoryName)
Throws:
PKIBaseException - If a PKI-error occurs
IllegalArgumentException - If publicPKIServerParameters does not contain hostName as key or the value is null

getPKICertificate

public byte[] getPKICertificate(Map userData)
                         throws PKIBaseException,
                                IllegalArgumentException
Gets a certificate of a user. The user is specified within the given userData-HashMap. Before the method setPublicPKIServer(...) has to be called.
Parameters:
userData - contains the needed userData to specify the user. For instance CN=John Smith,OU=Development,O=Living Systems,C=DE.
Returns:
userCertificate PEM format byte array of user format
Throws:
PKIBaseException - If a PKI-error occurs
IllegalArgumentException - If userData does not contain CN (Comon nameas) as key or value of CN is null

getInvalidPublicKeyCertificates

public ArrayList getInvalidPublicKeyCertificates(HashMap thePublicKeyCertificateCache)
                                          throws PKIBaseException
Gets the list of keys whose certificates are no longer valid. This method can only be called after the LDAP server parameters have been set.
Parameters:
thePublicKeyCertificateCache - cache of public key certificate
Returns:
a list of keys whose certificates are no longer valid.
Throws:
PKIBaseException - If a PKI-error occurs

checkTheValidityOfCachedCertificate

public void checkTheValidityOfCachedCertificate(byte[] oneCachedCertificate)
                                         throws PKIBaseException
Takes a byte array representation of a certificate, and checks it agains the current date. If OK, nothing is returned; if not, an exception will be thrown.
Parameters:
oneCachedCertificate - a byte array representation of a certificate
Throws:
PKIBaseException - If the certificate's validity has expired or it will be valid in future, not now

getNextCRLUpdateDate

public Date getNextCRLUpdateDate()
                          throws PKIBaseException
returns the date of next CRL update.
Returns:
date of next CRL update
Throws:
PKIBaseException - If LDAP exception happens.