Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.faceless.pdf2.viewer2
Class KeyStoreManager

java.lang.Object
  extended by org.faceless.pdf2.viewer2.KeyStoreManager

public class KeyStoreManager
extends Object

This class is a wrapper around a KeyStore, providing high-level management functions and the ability to load and save the KeyStore, selecting the file via a Swing dialog.

Each PDFViewer should have a KeyStoreManager if it needs to work with digital identities, which in practice means PDFs containing digital signatures (or that will have signatures added) or those encrypted with a public key. By default this class works with KeyStores stored in a file, although subclasses aren't bound by this. The default path for the KeyStore file is ${user.home}/.keystore, which is the default for the keytool supplied with the JDK. However this can be overridden by setting the file (and optionally password) properties, like this for an application: 

 java -Dorg.faceless.pdf2.viewer2.KeyStoreManager.file=/path/to/file.jks org.faceless.pdf2.viewer2.PDFViewer
or like this for an applet: 
 <applet code="org.faceless.pdf2.viewer2.PDFViewerApplet" name="pdfapplet" archive="bfopdf.jar">
  <param name="KeyStoreManager.file" value="/path/to/file.jks" />
  <param name="KeyStoreManager.password" value="secret" />
 </applet>
The type and provider attributes can be set as well, to determine which type of KeyStore to load. This is particularly useful for users on OS X - here's how to use the Mac OS X Keychain as the Java KeyStore (supported since 2.11.1): 
 java -Dorg.faceless.pdf2.viewer.KeyStoreManager.type=KeychainStore \
      -Dorg.faceless.pdf2.viewer.KeyStoreManager.provider=Apple org.faceless.pdf2.viewer2.PDFViewer
The ManageIdentities feature is a useful companion to this class and can be used to maintain the KeyStore, but it's not necessary for this classes operation.

This code is copyright the Big Faceless Organization. You're welcome to use, modify and distribute it in any form in your own projects, provided those projects continue to make use of the Big Faceless PDF library.

Since:
2.8.3, but a major rewrite in 2.11
See Also:
ManageIdentities, KeyStoreSignatureProvider, PublicKeyPromptEncryptionHandler, PDFViewer.getKeyStoreManager()

Field Summary
static FileFilter FILTER_CERTIFICATE
          A FileFilter that selects any X.509 Certificate file.
static FileFilter FILTER_KEYSTORE
          A FileFilter that selects any KeyStore file
static FileFilter FILTER_KEYSTORE_JKS
          A FileFilter that selects any JKS format KeyStore file
static FileFilter FILTER_KEYSTORE_PKCS12
          A FileFilter that selects any PKCS#12 format KeyStore file
 
Constructor Summary
KeyStoreManager()
           
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a Listener to changes to this KeyStore.
 void backupKeyStore()
          Back-up the state of the KeyStore so it can later be restored by restoreKeyStore()
 void commitKeyStore()
          Commit the state of the KeyStore by removing any existing backup
 boolean contains(Certificate cert)
          Indicates whether this key store contains the specified certificate.
 void createKeyStore()
          Initialize a new KeyStore for this object to manage.
 String createSelfSignedKey(String alias, String name, String unit, String organization, String city, String state, String country, char[] password, int days)
          Create a new 1024-bit RSA PrivateKey with self-signed X509Certificate, and add it to the KeyStore.
 void deleteEntry(String alias)
          Delete the specified entry (PrivateKey or X509Certificate) from the KeyStore
 void exportCertificate(OutputStream out, String alias)
          Export a public X509Certificate from the KeyStore to a DES-encoded Certificate file.
 void exportPKCS12Certificate(OutputStream out, String alias, char[] password)
          Export a PrivateKey and associated Certificate Chain from the KeyStore to a PKCS#12 object.
 KeyStore getKeyStore()
          Get the KeyStore managed by this object - will call loadKeyStore() if it's not already been called.
 char[] getKeyStorePassword()
          Return the default password to try when decrypting private keys.
 String[] importAllCertificates(File file, String alias)
          Import all the X.509 Certificates from the specified file into this KeyStore.
 String[] importAllCertificates(InputStream in, String alias, String format)
          Import all the X.509 Certificates from an InputStream into the KeyStore.
 String importCertificate(String alias, X509Certificate cert)
          Add the specified X.509 Certificate to the list of trusted root certificates.
 String importPrivateKey(KeyStore store, String alias, char[] password)
          Add a PrivateKey to the KeyStore.
 String importPrivateKey(PrivateKey key, Certificate[] certs, String alias, char[] password)
          Add a PrivateKey to the KeyStore.
 boolean isChanged()
          Return true if this KeyStore is "dirty" and needs to be saved to commit any changes, or false if no changes have been made.
 void loadKeyStore()
          Load the KeyStore this manager is supposed to work on.
 boolean loadKeyStore(JComponent root)
          Create a Swing component prompting the user to load the KeyStore.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remote a Listener form listening to changes to this KeyStore.
 void restoreKeyStore()
          Restore the state of the KeyStore to the last backup created by backupKeyStore()
 void saveKeyStore()
          Save the KeyStore, using the file and password specified in setFile().
 boolean saveKeyStore(JComponent root)
          Create a Swing compoment prompting the user to save the KeyStore.
 void setFile(File file, char[] password)
          Set the File this KeyStore is to be loaded from, or null to use the default as specified in the class API documentation.
 void setProvider(String provider)
          Set the Provider for the KeyStore - the parameter to KeyStore.getInstance(String, Provider).
 void setStoreType(String type)
          Set the type of KeyStore - the parameter to KeyStore.getInstance(String, Provider).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FILTER_KEYSTORE

public static final FileFilter FILTER_KEYSTORE
A FileFilter that selects any KeyStore file

Since:
2.11

FILTER_KEYSTORE_JKS

public static final FileFilter FILTER_KEYSTORE_JKS
A FileFilter that selects any JKS format KeyStore file

Since:
2.11

FILTER_KEYSTORE_PKCS12

public static final FileFilter FILTER_KEYSTORE_PKCS12
A FileFilter that selects any PKCS#12 format KeyStore file

Since:
2.11

FILTER_CERTIFICATE

public static final FileFilter FILTER_CERTIFICATE
A FileFilter that selects any X.509 Certificate file.

Since:
2.11
Constructor Detail

KeyStoreManager

public KeyStoreManager()
Method Detail

loadKeyStore

public void loadKeyStore()
                  throws IOException,
                         GeneralSecurityException
Load the KeyStore this manager is supposed to work on. This method will load the file specified by setFile(), and if it cannot be loaded this method will throw an Exception. Subclasses that don't manager KeyStores on the file system would override this method and saveKeyStore().

Throws:
IOException - if the KeyStore file cannot be accessed
GeneralSecurityException - if the KeyStore cannot be parsed or decoded

saveKeyStore

public void saveKeyStore()
                  throws IOException,
                         GeneralSecurityException
Save the KeyStore, using the file and password specified in setFile(). If no password was specified in that method an empty password is used.

Throws:
IOException - if the KeyStore file cannot be saved.
GeneralSecurityException - if the KeyStore cannot be saved for a cryptographic-related reason.

setStoreType

public void setStoreType(String type)
Set the type of KeyStore - the parameter to KeyStore.getInstance(String, Provider).

Parameters:
type - "JKS" to set a JKS keystore, "pkcs12" to set a PKCS#12 KeyStore or null to use the system default

setProvider

public void setProvider(String provider)
Set the Provider for the KeyStore - the parameter to KeyStore.getInstance(String, Provider).

Parameters:
provider - the Provider or null to use the default.

setFile

public void setFile(File file,
                    char[] password)
Set the File this KeyStore is to be loaded from, or null to use the default as specified in the class API documentation.

Parameters:
file - the File
password - the store password to verify the file, or null to not verify it

backupKeyStore

public void backupKeyStore()
Back-up the state of the KeyStore so it can later be restored by restoreKeyStore()

restoreKeyStore

public void restoreKeyStore()
Restore the state of the KeyStore to the last backup created by backupKeyStore()

commitKeyStore

public void commitKeyStore()
Commit the state of the KeyStore by removing any existing backup

createKeyStore

public void createKeyStore()
                    throws GeneralSecurityException
Initialize a new KeyStore for this object to manage. The KeyStore will use the values set by setType() and setProvider() or the system defaults.

Throws:
GeneralSecurityExeption - if the KeyStore cannot be created.
GeneralSecurityException

loadKeyStore

public boolean loadKeyStore(JComponent root)
Create a Swing component prompting the user to load the KeyStore. The initially selected file is the KeyStore managed by this object, if specified.

Parameters:
root - the JComponent to position the dialog relative too.
Returns:
true if a KeyStore was loaded, false otherwise

saveKeyStore

public boolean saveKeyStore(JComponent root)
Create a Swing compoment prompting the user to save the KeyStore. The initially selected file is the KeyStore managed by this object, if specified.

Parameters:
root - the JComponent to position the dialog relative too.
Returns:
true if the KeyStore was saved, false otherwise

getKeyStore

public final KeyStore getKeyStore()
                           throws GeneralSecurityException,
                                  IOException
Get the KeyStore managed by this object - will call loadKeyStore() if it's not already been called.

Throws:
GeneralSecurityException
IOException

isChanged

public boolean isChanged()
Return true if this KeyStore is "dirty" and needs to be saved to commit any changes, or false if no changes have been made.

getKeyStorePassword

public char[] getKeyStorePassword()
Return the default password to try when decrypting private keys. This is the password used when the KeyStore was loaded, as specfied in setFile(), and may be null.

importCertificate

public String importCertificate(String alias,
                                X509Certificate cert)
                         throws GeneralSecurityException
Add the specified X.509 Certificate to the list of trusted root certificates.

Parameters:
alias - the alias to store it under, or null to choose one
cert - the X.509 Certificate to store
Returns:
the name the Certificate was stored under, or null if the certificate already existed
Throws:
GeneralSecurityException - if the Certificate can not be imported

importAllCertificates

public String[] importAllCertificates(File file,
                                      String alias)
                               throws GeneralSecurityException,
                                      IOException
Import all the X.509 Certificates from the specified file into this KeyStore. The File may be a KeyStore file or a file that can be parsed by an X.509 CertificateFactory.

Parameters:
file - the File containing the X.509 Certificates
alias - the initial alias for the imports (may be null)
Returns:
a list of the aliases the Certificates were stored under
Throws:
IOException - if the Certificates can not be read due to File I/O reasons
GeneralSecurityException - if the Certificates can not be read for a cryptographic reason

importAllCertificates

public String[] importAllCertificates(InputStream in,
                                      String alias,
                                      String format)
                               throws GeneralSecurityException,
                                      IOException
Import all the X.509 Certificates from an InputStream into the KeyStore. The InputStream is closed on completion.

Parameters:
in - the InputStream to read the X.509 Certificates from
alias - if importing from a list of X.509 Certificates the alias to store the Certificate against, or null to pick one
format - one of "X.509", "JKS" or "pkcs12" to specify the format of in - a list of X.509 certificates, a JKS KeyStore or a PKCS#12 KeyStore
Returns:
a list of aliases added to the KeyStore
Throws:
IOException - if the Certificates can not be read due to File I/O reasons
GeneralSecurityException - if the Certificates can not be read for a cryptographic reason

importPrivateKey

public String importPrivateKey(KeyStore store,
                               String alias,
                               char[] password)
                        throws GeneralSecurityException
Add a PrivateKey to the KeyStore. The Key is loaded from the specified KeyStore

Parameters:
store - the KeyStore to load the private key from
alias - the name the private key is stored under
password - the password to access the private key
Throws:
GeneralSecurityException - if the Key could not be extracted or stored

importPrivateKey

public String importPrivateKey(PrivateKey key,
                               Certificate[] certs,
                               String alias,
                               char[] password)
                        throws GeneralSecurityException
Add a PrivateKey to the KeyStore.

Parameters:
key - the Key
certs - the Certificate chain
alias - a suggestion for the name the private key should be stored under
password - the password to encrypt the private key with
Throws:
GeneralSecurityException - if the Key could not be stored

exportPKCS12Certificate

public void exportPKCS12Certificate(OutputStream out,
                                    String alias,
                                    char[] password)
                             throws GeneralSecurityException,
                                    IOException
Export a PrivateKey and associated Certificate Chain from the KeyStore to a PKCS#12 object. The PKCS#12 object is written to the OutputStream, and the stream is left open on completion of this method.

Parameters:
out - the OutputStream
alias - the alias of the entry to export
password - the password used to access the private key
Throws:
IOException - if an I/O exception occurs while writing
GeneralSecurityException - if the PrivateKey cannot be extracted from the KeyStore

contains

public boolean contains(Certificate cert)
                 throws GeneralSecurityException,
                        IOException
Indicates whether this key store contains the specified certificate.

Parameters:
cert - the certificate to test
Throws:
GeneralSecurityException
IOException

exportCertificate

public void exportCertificate(OutputStream out,
                              String alias)
                       throws GeneralSecurityException,
                              IOException
Export a public X509Certificate from the KeyStore to a DES-encoded Certificate file. The file is written to the specified OutputStream, and the stream is left open on completion of this method.

Parameters:
out - the OutputStream
alias - the alias of the entry to export
Throws:
IOException - if an I/O exception occurs while writing
GeneralSecurityException - if the Certificate cannot be extracted from the KeyStore

deleteEntry

public void deleteEntry(String alias)
                 throws GeneralSecurityException
Delete the specified entry (PrivateKey or X509Certificate) from the KeyStore

Parameters:
alias - the entry to delete
Throws:
GeneralSecurityException - if the entry cannot be deleted from the KeyStore

createSelfSignedKey

public String createSelfSignedKey(String alias,
                                  String name,
                                  String unit,
                                  String organization,
                                  String city,
                                  String state,
                                  String country,
                                  char[] password,
                                  int days)
                           throws GeneralSecurityException
Create a new 1024-bit RSA PrivateKey with self-signed X509Certificate, and add it to the KeyStore.

Parameters:
alias - the alias to store it as
name - the CN of the X.509 certificate DN
unit - the OU of the X.509 certificate DN
organization - the O of the X.509 certificate DN
city - the L of the X.509 certificate DN
country - the C of the X.509 certificate DN
password - the password to store the key with
days - the number of days the Key is valid for from now.
Returns:
the alias the new Key is stored under in the KeyStore
Throws:
GeneralSecurityException - if something goes wrong

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a Listener to changes to this KeyStore. A PropertyChangeEvent occurs when a new entry is added or removed from the KeyStore managed by this KeyStoreManager. Duplicate PropertyChangeListeners are ignored and listeners are held in this class with a weak-reference and so will be removed automatically on garbage collection.

Parameters:
listener - the Listener.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remote a Listener form listening to changes to this KeyStore.

Parameters:
listener - a listener previously added in addPropertyChangeListener().
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2001-2009 Big Faceless Organization