KeyAndCertificateSource ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.KeyAndCertificateSource

All Implemented Interfaces:

KeyAndCertContainer
```
public class KeyAndCertificateSource
extends java.lang.Object
implements KeyAndCertContainer
```
This class acts as a source of private keys and certificates for use when creating or decoding messages.
There are two basic ways to use this class. One is to supply a User object, and let default values be extracted from there. The default values can later be changed via the set methods. The other way is to supply a CertVerifier object to the constructor, and manually set the required information via the set methods.
The methods of this class are not thread-safe. However, once the object is initialized, the get methods can be safely used in multiple threads.

Since:

7.0

See Also:
User

Constructor Summary

Constructors
Constructor and Description
`KeyAndCertificateSource()` Create a new `KeyAndCertificateSource` object.
`KeyAndCertificateSource(CertVerifier certVerifier)` Create a new `KeyAndCertificateSource` object.
`KeyAndCertificateSource(User user)` Create a new `KeyAndCertificateSource` object.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addDecryptionKeyInfo(java.security.PrivateKey decryptionKey, X509Certificate encryptionCertificate)` Adds the given key as a decryption key.
`X509Certificate[]`	`getCaCertificateChain()` Returns the CaCertificate chain that was added using the `setCaChain(X509Certificate[])` method.
`X509Certificate`	`getCertificate(Name issuerDN, java.math.BigInteger serialNumber)` Returns the certificate that matches the given issuer DN and serial number.
`X509Certificate[]`	`getCertificateChain()` Returns the certificate chain associated with this object.
`CollectionCS`	`getCertificateStore()` Returns the Certificate Store associated with this object.
`CollectionCS`	`getCertStore()` Deprecated. use getCertificateStore()
`CertVerifier`	`getCertVerifier()` Returns the Certificate verifier associated with this object.
`java.security.PrivateKey`	`getDecryptionKey(Name issuerDN, java.math.BigInteger serialNumber)` Returns the private key that matches the given issuer DN and serial number.
`java.security.PrivateKey`	`getDecryptionKey(Name issuer, java.lang.String serialNumber)` Convienance method for returning the private key that matches the given issuer DN and serial number.
`X509Certificate`	`getEncryptionCertificate()` Returns the encryption certificate associated with this object.
`java.security.PrivateKey`	`getSigningKey()` Returns the private signing key associated with this object.
`X509Certificate`	`getVerificationCertificate()` Returns the verification certificate associated with this object.
`void`	`setCaChain(X509Certificate[] certChain)` Sets the certificate chain.
`void`	`setEncryptionCertificate(X509Certificate encryptionCertificate)` Sets the encryption certificate to be used when encrypting a message.
`void`	`setSigningInfo(java.security.PrivateKey signingKey, X509Certificate verificationCertificate)` Sets the private signing key and verification certificate to be used when signing a message.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - KeyAndCertificateSource
```
public KeyAndCertificateSource()
```
    Create a new KeyAndCertificateSource object. All certificate and key fields are initialized to null.
  - KeyAndCertificateSource
```
public KeyAndCertificateSource(CertVerifier certVerifier)
```
    Create a new KeyAndCertificateSource object. All certificate and key fields are initialized to null.
    
    Parameters:
    certVerifier - the object that will perform all certificate validation.
  - KeyAndCertificateSource
```
public KeyAndCertificateSource(User user)
                        throws UserFatalException,
                               UserNotLoggedInException
```
    Create a new KeyAndCertificateSource object. All certificate and key fields are initialized to fields extracted from the given User object, via the User.getSigningKey(), User.getVerificationCertificate(), and User.getEncryptionCertificate() methods. When needed, decryption keys are obtained from the given User object via the User.getUserPrivateKey(Name, BigInteger) method.
    
    Parameters:
    user - the User object from which to extract all certificates and keys.
    
    Throws:
    
    UserFatalException - if no certificate chain can be found to a root CA.
    
    UserNotLoggedInException - if user is not logged in.
    See Also:
    User
- Method Detail
  - getCertStore
```
public CollectionCS getCertStore()
```
    Deprecated. use getCertificateStore()
    
    Returns the Certificate Store associated with this object.
    
    Returns:
    the Certificate Store associated with this object.
  - getCertificateStore
```
public CollectionCS getCertificateStore()
```
    Returns the Certificate Store associated with this object. This method can be called using the KeyAndCertContainer interface.
    
    Specified by:
    
    getCertificateStore in interface KeyAndCertContainer
    
    Returns:
    the Certificate Store associated with this object.
    Since:
    
    7.2
  - getCertVerifier
```
public CertVerifier getCertVerifier()
```
    Returns the Certificate verifier associated with this object.
    
    Returns:
    the Certificate verifier associated with this object.
  - getSigningKey
```
public java.security.PrivateKey getSigningKey()
```
    Returns the private signing key associated with this object. Returns null if there is no key.
    
    Specified by:
    
    getSigningKey in interface KeyAndCertContainer
    
    Returns:
    the private signing key associated with this object.
  - getVerificationCertificate
```
public X509Certificate getVerificationCertificate()
```
    Returns the verification certificate associated with this object. Returns null if there is no certificate.
    
    Specified by:
    
    getVerificationCertificate in interface KeyAndCertContainer
    
    Returns:
    the verification certificate key associated with this object.
  - getEncryptionCertificate
```
public X509Certificate getEncryptionCertificate()
```
    Returns the encryption certificate associated with this object. Returns null if there is no certificate.
    
    Specified by:
    
    getEncryptionCertificate in interface KeyAndCertContainer
    
    Returns:
    the encryption certificate key associated with this object.
  - getDecryptionKey
```
public java.security.PrivateKey getDecryptionKey(Name issuerDN,
                                        java.math.BigInteger serialNumber)
```
    Returns the private key that matches the given issuer DN and serial number. Returns null if there is no matching key.
    If this object was constructed by supplying a User object, keys are obtained from there. If not, or if the user did not have the required key, the given issuer name and serial number must match those of one of the certificates added via addDecryptionKeyInfo(PrivateKey,X509Certificate).
    
    Parameters:
    issuerDN - the name of the key issuer
    serialNumber - the serial number of the key.
    
    Returns:
    the private key that matches the given issuer DN and serial number.
  - getCertificate
```
public X509Certificate getCertificate(Name issuerDN,
                             java.math.BigInteger serialNumber)
```
    Returns the certificate that matches the given issuer DN and serial number. Returns null if there is no matching certificate.
    This method first checks certificates from the underlying User object. If a certificate is not found, all certificates added by the addDecryptionKeyInfo(PrivateKey, X509Certificate) method are checked.
    
    Parameters:
    issuerDN - the name of the certificate issuer
    serialNumber - the serial number of the certificate.
    
    Returns:
    the certificate that matches the given issuer DN and serial number. If no certificate is found, return null.
  - getCertificateChain
```
public X509Certificate[] getCertificateChain()
```
    Returns the certificate chain associated with this object. Returns an array containing the root of trust if no chain has been set. Returns an empty array if neither have been set.
    
    Returns:
    the certificate chain associated with this object.
  - setSigningInfo
```
public void setSigningInfo(java.security.PrivateKey signingKey,
                  X509Certificate verificationCertificate)
                    throws java.security.InvalidKeyException,
                           java.lang.NullPointerException
```
    Sets the private signing key and verification certificate to be used when signing a message. The KeyUsage extension in the certificate must indicate that the key can be used for signature purposes.
    Note that no check is made to ensure the public key in the certificate matches the given private key, but if they do not match, and message created will not be verifiable.
    
    Parameters:
    signingKey - the private key to be used for signing.
    verificationCertificate - the certificate to be included in the signed message for signature verification purposes.
    
    Throws:
    
    java.security.InvalidKeyException - if the given key is not appropriate for signing.
    
    java.lang.NullPointerException - if any of the parameters are null.
  - setEncryptionCertificate
```
public void setEncryptionCertificate(X509Certificate encryptionCertificate)
```
    Sets the encryption certificate to be used when encrypting a message.
    
    Parameters:
    encryptionCertificate - The message encryptor's encryption certificate.
  - addDecryptionKeyInfo
```
public void addDecryptionKeyInfo(java.security.PrivateKey decryptionKey,
                        X509Certificate encryptionCertificate)
```
    Adds the given key as a decryption key. When decrypting a message, it must have been encrypted for at least one of the certificates added via this method.
    Note that no check is made to ensure the public key in the certificate matches the given private key.
    
    When searching for keys using getDecryptionKey(Name,BigInteger), or certificates using getCertificate(Name,BigInteger) matching is done against the issuer DN and serial number fields of encryptionCertificate
    
    Even if this object was created with the constructor that accepts a User, this method can be used to add additional decryption keys.
    
    Parameters:
    decryptionKey - The private decryption key to add.
    encryptionCertificate - The encryption certificate that matches the decryption key.
  - setCaChain
```
public void setCaChain(X509Certificate[] certChain)
```
    Sets the certificate chain. This array should contain all certificates required to build a path from the verification and encryption certificates to a root certificate.
    
    Parameters:
    certChain - the certificate chain.
  - getCaCertificateChain
```
public X509Certificate[] getCaCertificateChain()
```
    Returns the CaCertificate chain that was added using the setCaChain(X509Certificate[]) method. If the chain is null, it will check to see if a CertVerifier has been set, and if so it will retrieve the trusted root from this object.
    
    Specified by:
    
    getCaCertificateChain in interface KeyAndCertContainer
    
    Returns:
    the certificate chain associated with this object.
    Since:
    
    7.2
    
    See Also:
    getCertificateChain()
  - getDecryptionKey
```
public java.security.PrivateKey getDecryptionKey(Name issuer,
                                        java.lang.String serialNumber)
                                          throws UserNotLoggedInException
```
    Convienance method for returning the private key that matches the given issuer DN and serial number. Accepts the serialNumber as a String. This method can also be called using the KeyAndCertContainer interface.
    Calls getDecryptionKey(Name, BigInteger)
    
    Specified by:
    
    getDecryptionKey in interface KeyAndCertContainer
    
    Parameters:
    issuer - the name of the key issuer
    serialNumber - the String of the serial number.
    
    Returns:
    the private key that matches the given issuer DN and serial number.
    
    Throws:
    
    UserNotLoggedInException - if the user is not logged in.
    Since:
    
    7.2
    
    See Also:
    getDecryptionKey(Name, BigInteger)

Class KeyAndCertificateSource

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

KeyAndCertificateSource

KeyAndCertificateSource

KeyAndCertificateSource

Method Detail

getCertStore

getCertificateStore

getCertVerifier

getSigningKey

getVerificationCertificate

getEncryptionCertificate

getDecryptionKey

getCertificate

getCertificateChain

setSigningInfo

setEncryptionCertificate

addDecryptionKeyInfo

setCaChain

getCaCertificateChain

getDecryptionKey