|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.viewer2.KeyStoreManager
public class KeyStoreManager
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.
If nothing else is specified, the default KeyStore
used is a JKS KeyStore
loaded from the file ${user.home}/.keystore
, which is the default
for the keytool
supplied with the JDK. The path to the file can be changed
by setting the file
parameter, and the password with the "password"
parameter. The KeyStore type
parameter can be jks
(the
default, and used for jceks
keystores as well) or pkcs12
if
the KeyStore is in PKCS#12 format. Here's how to do this for an application
java -Dorg.faceless.pdf2.viewer2.KeyStoreManager.params="type=pkcs12;file=/path/to/file.p12" org.faceless.pdf2.viewer2.PDFVieweror like this for an applet:
<applet code="org.faceless.pdf2.viewer2.PDFViewerApplet" name="pdfapplet" archive="bfopdf.jar"> <param name="KeyStoreManager.params" value="type=jks;file='/path/to/file.jks';password='secret'" /> </applet>
Certificates and keys stored in the Apple OS X "KeyChain" can be accessed by setting the
provider
parameter to "Apple" and the type
parameter to "KeychainStore". No
other parameters are required. There are some issues with this KeyStore - in particular, at least until
OS X 10.6 only the first private key in the KeyStore can be accessed. Here's an example.
java -Dorg.faceless.pdf2.viewer2.KeyStoreManager.params=type=KeychainStore\;provider=Apple org.faceless.pdf2.viewer2.PDFViewer
Since 2.11.14 it's possible to use a PKCS#11 based Hardware Security Module (HSM) as a KeyStore. The
attributes supplied to the sun.security.pkcs11.SunPKCS11
Provider (specified
here)
can be supplied directly as parameters, and the type
parameter must be set to "pkcs11".
For example, here's how to use a
Safenet eToken Pro
on Windows as a KeyStore: for an explanation of how to parse the parameterss see the setParameters(java.lang.String)
method.
java -Dorg.faceless.pdf2.viewer2.KeyStoreManager.params="type=pkcs11;name=eToken;library='c:\\WINDOWS\\system32\\eTPKCS11.dll';password=1234" 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 class's 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.
ManageIdentities
,
KeyStoreSignatureProvider
,
PublicKeyPromptEncryptionHandler
,
PDFViewer.getKeyStoreManager()
Field Summary | |
---|---|
protected boolean |
changed
|
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/JCEKS format KeyStore file |
static FileFilter |
FILTER_KEYSTORE_PKCS12
A FileFilter that selects any PKCS#12 format KeyStore file |
protected KeyStore |
keystore
|
protected Map |
params
|
protected WeakPropertyChangeSupport |
propertyChangeSupport
|
protected PropertyManager |
propertymanager
|
Constructor Summary | |
---|---|
KeyStoreManager(PDFViewer viewer)
Create a new KeyStoreManager |
Method Summary | |
---|---|
void |
addPropertyChangeListener(PropertyChangeListener listener)
Add a Listener to changes to this KeyStore . |
void |
cancelKeyStore()
Cancel any changes to the current keystore. |
boolean |
canCreateSelfSignedCertificate()
Return true if this KeyStoreManager has permission to create a new self-signed certificate. |
boolean |
canStoreSecretKeys()
Return true if this KeyStore can store Secret (symmetric) key information. |
boolean |
canStoreSecretKeysOnConversion()
Return true if this KeyStore can store Secret (symmetric) key information, or can be converted to one that can. |
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 2048-bit RSA PrivateKey with self-signed X509Certificate ,
and add it to the KeyStore . |
String |
createSelfSignedKey(String alias,
String name,
String unit,
String organization,
String city,
String state,
String country,
char[] password,
int days,
String algorithm,
int keylength)
Create a new PrivateKey of the specified algorithm, 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. |
String |
getParameter(String key)
Return a parameter set by setParameter(java.lang.String, java.lang.String) |
SecretKey |
getSecret(String alias,
String type,
char[] password)
Get a secret value from the KeyStore, as set by putSecret() |
String |
getStoreType()
Get the KeyStore type |
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 |
isCancellable()
Return true if changes to the KeyStore can be cancelled, or false if they're committed immediately |
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. |
boolean |
isFileBased()
Return true if the KeyStore is file based, false otherwise. |
void |
loadKeyStore()
Load the KeyStore this manager is supposed to work on, based on the
parameters specified. |
boolean |
loadKeyStore(JComponent root)
Create a Swing component prompting the user to load the KeyStore . |
void |
putSecret(String alias,
SecretKey key,
char[] password)
Store a secret value in the KeyStore - any data which needs to be password protected. |
void |
removePropertyChangeListener(PropertyChangeListener listener)
Remote a Listener form listening to changes to this KeyStore . |
void |
saveKeyStore()
Save the KeyStore using the setParameter(java.lang.String, java.lang.String) parameters specified for
this class - for file-based KeyStores like JKS, JCEKS and PKCS#12, this requires the file
parameter and optionally the password parameter too (if no password is specified,
the empty string is used). |
boolean |
saveKeyStore(JComponent root)
Create a Swing compoment prompting the user to save the KeyStore . |
void |
setFile(File file,
char[] password)
Deprecated. call setParameter with "file" and "password" as keys |
void |
setParameter(String key,
String value)
Set a parameter to be used when loading or saving the KeyStore. |
void |
setParameters(String in)
Set the store parameters. |
void |
setProvider(String provider)
Deprecated. call setParameter with "provider" as the key |
void |
setStoreType(String type)
Deprecated. call setParameter with "type" as the key |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final FileFilter FILTER_KEYSTORE
FileFilter
that selects any KeyStore
file
public static final FileFilter FILTER_KEYSTORE_JKS
FileFilter
that selects any JKS/JCEKS format KeyStore
file
public static final FileFilter FILTER_KEYSTORE_PKCS12
FileFilter
that selects any PKCS#12 format KeyStore
file
public static final FileFilter FILTER_CERTIFICATE
FileFilter
that selects any X.509 Certificate
file.
protected WeakPropertyChangeSupport propertyChangeSupport
protected KeyStore keystore
protected Map params
protected final PropertyManager propertymanager
protected boolean changed
Constructor Detail |
---|
public KeyStoreManager(PDFViewer viewer)
viewer
- the ViewerMethod Detail |
---|
public void loadKeyStore() throws IOException, GeneralSecurityException
KeyStore
this manager is supposed to work on, based on the
parameters
specified. These will typically include the
file
and password
parameters. If the KeyStore cannot
be loaded, this method will throw an Exception
Subclasses that need to manage their own KeyStore will typically override this
method and saveKeyStore()
.
IOException
- if the KeyStore file cannot be accessed
GeneralSecurityException
- if the KeyStore cannot be parsed or decodedpublic void saveKeyStore() throws IOException, GeneralSecurityException
KeyStore
using the setParameter(java.lang.String, java.lang.String)
parameters specified for
this class - for file-based KeyStores like JKS, JCEKS and PKCS#12, this requires the file
parameter and optionally the password
parameter too (if no password is specified,
the empty string is used).
IOException
- if the KeyStore file cannot be saved.
GeneralSecurityException
- if the KeyStore cannot be saved for a cryptographic-related reason.public void setParameters(String in)
setParameter(java.lang.String, java.lang.String)
.
For instance, the following method calls are the same:
setParameters("type=pkcs11;name=eToken;library='/usr/lib/libeTPkcs11.so';enabledMechanisms='{CKM_RSA_PKCS CKM_RSA_PKCS_KEY_PAIR_GEN};attributes(*,CKO_PRIVATE_KEY,*)='{\\nCKA_SIGN=true\\nCKA_DECRYPT=true\\n}'"); setParameter("type", "pkcs11"); setParameter("name", "eToken"); setParameter("library", "/usr/lib/libeTPkcs11.so"); setParameter("enabledMechanisms", "{CKM_RSA_PKCS CKM_RSA_PKCS_KEY_PAIR_GEN}"); setParameter("attribute(*,CKO_PRIVATE_KEY,*)", "{\nCKA_SIGN=true\nCKA_DECRYPT=true\n}");Characters can be quoted or preceded with a backslash to treat them as literals.
public void setParameter(String key, String value)
type | The KeyStore type: one of "jks", "jceks", "pkcs12", "pkcs11" or "keychainstore" |
---|---|
provider | The KeyStore provider |
file | For jks, jceks and pkcs12 KeyStores, the file to save the KeyStore in |
password | The store password for the KeyStore |
keylength | When creating new key pairs, the number of bits to use for the key (default is 2048) |
sigalg | When creating new key pairs, the algorith, to use (default is SHA1withRSA) |
public String getParameter(String key)
setParameter(java.lang.String, java.lang.String)
public void setStoreType(String type)
type
- the KeyStore typepublic String getStoreType()
public void setProvider(String provider)
provider
- the KeyStore providerpublic void setFile(File file, char[] password)
file
- the KeyStore filepassword
- the KeyStore passwordpublic void cancelKeyStore()
public void createKeyStore() throws GeneralSecurityException
KeyStore
for this object to manage. The KeyStore
will use the values set by setType()
and setProvider()
or the system defaults.
GeneralSecurityExeption
- if the KeyStore cannot be created.
GeneralSecurityException
public boolean isFileBased()
public boolean isCancellable()
public boolean loadKeyStore(JComponent root)
KeyStore
.
The initially selected file is the KeyStore
managed by this object, if specified.
root
- the JComponent to position the dialog relative too.
public boolean saveKeyStore(JComponent root)
KeyStore
.
The initially selected file is the KeyStore managed by this object, if specified.
root
- the JComponent to position the dialog relative too.
public KeyStore getKeyStore() throws GeneralSecurityException, IOException
KeyStore
managed by this object - will call loadKeyStore()
if it's
not already been called.
GeneralSecurityException
IOException
public boolean isChanged()
KeyStore
is "dirty" and needs to be saved to commit
any changes, or false if no changes have been made.
public String importCertificate(String alias, X509Certificate cert) throws GeneralSecurityException
alias
- the alias to store it under, or null
to choose onecert
- the X.509 Certificate to store
null
if
the certificate already existed
GeneralSecurityException
- if the Certificate can not be importedpublic String[] importAllCertificates(File file, String alias) throws GeneralSecurityException, IOException
KeyStore
.
The File may be a KeyStore
file or a file that can be parsed by an X.509
CertificateFactory
.
file
- the File containing the X.509 Certificatesalias
- the initial alias for the imports (may be null
)
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 reasonpublic String[] importAllCertificates(InputStream in, String alias, String format) throws GeneralSecurityException, IOException
InputStream
into the KeyStore
.
The InputStream is closed on completion.
in
- the InputStream to read the X.509 Certificates fromalias
- if importing from a list of X.509 Certificates the alias
to store the Certificate against, or null
to pick oneformat
- one of "X.509", "JKS" or "pkcs12" to specify the format of
in
- a list of X.509 certificates, a JKS/JCEKS KeyStore or a PKCS#12
KeyStore
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 reasonpublic String importPrivateKey(KeyStore store, String alias, char[] password) throws GeneralSecurityException
PrivateKey
to the KeyStore
. The Key is loaded from the specified KeyStore
store
- the KeyStore to load the private key fromalias
- the name the private key is stored underpassword
- the password to access the private key
GeneralSecurityException
- if the Key could not be extracted or storedpublic String importPrivateKey(PrivateKey key, Certificate[] certs, String alias, char[] password) throws GeneralSecurityException
PrivateKey
to the KeyStore
.
key
- the Keycerts
- the Certificate chainalias
- a suggestion for the name the private key should be stored underpassword
- the password to encrypt the private key with
GeneralSecurityException
- if the Key could not be storedpublic void exportPKCS12Certificate(OutputStream out, String alias, char[] password) throws GeneralSecurityException, IOException
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.
out
- the OutputStreamalias
- the alias of the entry to exportpassword
- the password used to access the private key
IOException
- if an I/O exception occurs while writing
GeneralSecurityException
- if the PrivateKey cannot be extracted from the KeyStorepublic boolean contains(Certificate cert) throws GeneralSecurityException, IOException
cert
- the certificate to test
GeneralSecurityException
IOException
public void exportCertificate(OutputStream out, String alias) throws GeneralSecurityException, IOException
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.
out
- the OutputStreamalias
- the alias of the entry to export
IOException
- if an I/O exception occurs while writing
GeneralSecurityException
- if the Certificate cannot be extracted from the KeyStorepublic void deleteEntry(String alias) throws GeneralSecurityException
PrivateKey
or X509Certificate
) from the
KeyStore
alias
- the entry to delete
GeneralSecurityException
- if the entry cannot be deleted from the KeyStorepublic boolean canStoreSecretKeysOnConversion()
canStoreSecretKeys()
public boolean canStoreSecretKeys()
canStoreSecretKeysOnConversion()
public void putSecret(String alias, SecretKey key, char[] password) throws GeneralSecurityException, IOException
alias
- the aliaskey
- the key to store, or null to delete any secret key with this aliaspassword
- the password that will be used to encrypt this data.
if null, the KeyStore password is tried.
GeneralSecurityException
IOException
public SecretKey getSecret(String alias, String type, char[] password) throws GeneralSecurityException
putSecret()
alias
- the aliaspassword
- the password - if null, the KeyStore password is tried.
GeneralSecurityException
public String createSelfSignedKey(String alias, String name, String unit, String organization, String city, String state, String country, char[] password, int days) throws GeneralSecurityException
PrivateKey
with self-signed X509Certificate
,
and add it to the KeyStore
.
alias
- the alias to store it asname
- the CN of the X.509 certificate DNunit
- the OU of the X.509 certificate DNorganization
- the O of the X.509 certificate DNcity
- the L of the X.509 certificate DNcountry
- the C of the X.509 certificate DNpassword
- the password to store the key withdays
- the number of days the Key is valid for from now.
GeneralSecurityException
- if something goes wrongpublic String createSelfSignedKey(String alias, String name, String unit, String organization, String city, String state, String country, char[] password, int days, String algorithm, int keylength) throws GeneralSecurityException
PrivateKey
of the specified algorithm, with self-signed X509Certificate
,
and add it to the KeyStore
.
alias
- the alias to store it asname
- the CN of the X.509 certificate DNunit
- the OU of the X.509 certificate DNorganization
- the O of the X.509 certificate DNcity
- the L of the X.509 certificate DNcountry
- the C of the X.509 certificate DNpassword
- the password to store the key withdays
- the number of days the Key is valid for from now.algorithm
- the Signature algorithm, eg "SHA1withRSA", "SHA256withRSA", "SHA256withDSA"keylength
- the length of the key in bits, eg 1024, 2048, 4096
GeneralSecurityException
- if something goes wrongpublic boolean canCreateSelfSignedCertificate()
public void addPropertyChangeListener(PropertyChangeListener listener)
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.
listener
- the Listener.public void removePropertyChangeListener(PropertyChangeListener listener)
KeyStore
.
listener
- a listener previously added in addPropertyChangeListener()
.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |