JXTA

net.jxta.impl.protocol
Class PSEConfigAdv

java.lang.Object
  extended by net.jxta.document.Advertisement
      extended by net.jxta.document.ExtendableAdvertisement
          extended by net.jxta.impl.protocol.PSEConfigAdv
All Implemented Interfaces:
Cloneable

public final class PSEConfigAdv
extends ExtendableAdvertisement
implements Cloneable

Contains parameters for configuration of the PSE Membership Service.

The configuration advertisement can include an optional seed certificate chain and encrypted private key. If this seed information is present the PSE Membership Service will require an initial authentication to unlock the encrypted private key before creating the PSE keystore. The newly created PSE keystore will be "seeded" with the certificate chain and the private key.

This mechanism allows for out-of-band distribution of JXTA identity information and avoids the need for remote authentication.

Note: This implementation contemplates multiple root certs in its schema, but the API has not yet been extended to include this functionality.


Nested Class Summary
static class PSEConfigAdv.Instantiator
          Instantiator for PSEConfigAdv
 
Method Summary
 PSEConfigAdv clone()
          
static String getAdvertisementType()
          Returns the identifying type of this Advertisement.
 String getAdvType()
          Returns the identifying type of this Advertisement.
 String getBaseAdvType()
          Returns the base type of this advertisement hierarchy.
 String getCert()
          Returns the seed certificate encoded as a BASE64 String.
 X509Certificate getCertificate()
          Returns the seed certificate.
 X509Certificate[] getCertificateChain()
          Returns the seed certificate chain.
 Document getDocument(MimeMediaType encodeAs)
          Write this advertisement into a document of the requested type.
 EncryptedPrivateKeyInfo getEncryptedPrivateKey()
          Get the encrypted seed private key from this advertisement.
 String getEncryptedPrivateKeyAlgo()
          Get the encrypted seed private key algorithm from this advertisement.
 String getEncryptedPrivKey()
          Get the encrypted seed private key from this advertisement.
 ID getID()
          Returns an ID which identifies this Advertisement as uniquely as possible.
 String[] getIndexFields()
          Returns the element names on which this advertisement should be indexed.
 URI getKeyStoreLocation()
          Return the location of the Keystore or null if the PSE Membership Service should use the default location.
 String getKeyStoreProvider()
          Return the JCE provider which the PSE Membership Service should use for Keystores.
 String getKeyStoreType()
          Return the JCE Keystore type which the PSE Membership Service should use.
 PrivateKey getPrivateKey(char[] password)
          Get the seed private key from this advertisement.
protected  boolean handleElement(Element raw)
          Process an individual element from the document during parse.
 void setCert(String newCert)
          Sets the seed certificate for this peer from a BASE64 String.
 void setCertificate(X509Certificate newCert)
          Sets the seed certificate for this peer.
 void setCertificateChain(X509Certificate[] newCerts)
          Sets the seed Certificate chain for this peer.
 void setEncryptedPrivateKey(EncryptedPrivateKeyInfo newPriv, String algorithm)
          Set the encrypted seed private key for this advertisement.
 void setEncryptedPrivateKey(String newPriv, String algorithm)
          Set the encrypted private key for this advertisement.
 void setKeyStoreLocation(URI location)
          Set the location of the Keystore or null if the PSE Membership Service should use the default location.
 void setKeyStoreProvider(String provider)
          Set the JCE provider which the PSE Membership Service should use for Keystores.
 void setKeyStoreType(String type)
          Set the JCE Keystore type which the PSE Membership Service should use.
 void setPrivateKey(PrivateKey newPriv, char[] password)
          Set the encrypted seed private key for this advertisement.
 
Methods inherited from class net.jxta.document.ExtendableAdvertisement
handleAttribute
 
Methods inherited from class net.jxta.document.Advertisement
toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getAdvertisementType

public static String getAdvertisementType()
Returns the identifying type of this Advertisement.

Note: This is a static method. It cannot be used to determine the runtime type of an advertisement. ie.

      Advertisement adv = module.getSomeAdv();
      String advType = adv.getAdvertisementType();
  

This is wrong and does not work the way you might expect. This call is not polymorphic and calls Advertisement.getAdvertisementType() no matter what the real type of the advertisement.

Returns:
String the type of advertisement

clone

public PSEConfigAdv clone()

Overrides:
clone in class Advertisement

getAdvType

public String getAdvType()
Returns the identifying type of this Advertisement. Unlike Advertisement.getAdvertisementType() this method will return the correct runtime type of an Advertisement object.

This implementation is provided for existing advertisements which do not provide their own implementation. In most cases you should provide your own implementation for efficiency reasons.

Overrides:
getAdvType in class Advertisement
Returns:
The identifying type of this Advertisement.

getBaseAdvType

public final String getBaseAdvType()
Returns the base type of this advertisement hierarchy. Typically, only the most basic advertisement of a type will implement this method and declare it as final.

Specified by:
getBaseAdvType in class ExtendableAdvertisement
Returns:
String the base type of advertisements in this hierarchy.

getID

public ID getID()
Returns an ID which identifies this Advertisement as uniquely as possible. This ID is typically used as the primary key for indexing of the Advertisement within databases.

Each advertisement sub-class must choose an appropriate implementation which returns canonical and relatively unique ID values for it's instances. Since this ID is commonly used for indexing, the IDs returned must be as unique as possible to avoid collisions. The value for the ID returned can either be:

For Advertisement types which normally return non-ID.nullID values no ID should be returned when asked to generate an ID while the Advertisement is an inconsistent state (example: uninitialized index fields). Instead IllegalStateException should be thrown.

Specified by:
getID in class Advertisement
Returns:
An ID that relatively uniquely identifies this advertisement or ID.nullID if this advertisement is of a type that is not normally indexed.

getCertificate

public X509Certificate getCertificate()
Returns the seed certificate. If present, this certificate will be used to initialize the PSE keystore and will be stored using the peer id of the authenticating peer.

Returns:
The seed certificate or null if there is no seed certificate defined.

getCertificateChain

public X509Certificate[] getCertificateChain()
Returns the seed certificate chain. If present, this certificate chain will be used to initialize the PSE keystore and will be stored using the peer id of the authenticating peer.

Returns:
the seed certificate chain for this peer or null if there is no seed certificate chain defined.

getCert

public String getCert()
Returns the seed certificate encoded as a BASE64 String.

Returns:
the seed certificate encoded as a BASE64 String.

setCert

public void setCert(String newCert)
Sets the seed certificate for this peer from a BASE64 String.

Parameters:
newCert - The seed certificate for this peer as a BASE64 String.

setCertificate

public void setCertificate(X509Certificate newCert)
Sets the seed certificate for this peer. If null then the Private Key is also cleared.

Parameters:
newCert - The seed certificate for this PSE instance or null to clear the seed certificates and private key.

setCertificateChain

public void setCertificateChain(X509Certificate[] newCerts)
Sets the seed Certificate chain for this peer. If null then the Private Key is also cleared.

Parameters:
newCerts - The seed certificate chain or null to clear the seed certificates and private key.

getPrivateKey

public PrivateKey getPrivateKey(char[] password)
Get the seed private key from this advertisement. The private key is retrieved from the advertisement using the provided password.

Parameters:
password - the password to use in attempting to decrypt the private key.
Returns:
the decrypted private key.

getEncryptedPrivateKey

public EncryptedPrivateKeyInfo getEncryptedPrivateKey()
Get the encrypted seed private key from this advertisement.

Returns:
the encrypted seed private key.

getEncryptedPrivateKeyAlgo

public String getEncryptedPrivateKeyAlgo()
Get the encrypted seed private key algorithm from this advertisement.

Returns:
the decrypted seed private key algorithm.

getEncryptedPrivKey

public String getEncryptedPrivKey()
Get the encrypted seed private key from this advertisement.

Returns:
the encoded encrypted private key, a BASE64 String of a DER encoded PKCS8 EncrpytePrivateKeyInfo.

getKeyStoreType

public String getKeyStoreType()
Return the JCE Keystore type which the PSE Membership Service should use. This value should be the name of valid JCE Keystore or null if the default Keystore type should be used. The PSE Membership Service will create the keystore via KeyStore.getInstance(keystore_type).

Returns:
The name of the Keystore type which the PSE Membership Service will use or null if the default keystore type should be used.

setKeyStoreType

public void setKeyStoreType(String type)
Set the JCE Keystore type which the PSE Membership Service should use. This value should be the name of valid JCE Keystore or null if the default Keystore type should be used. The PSE Membership Service will create the keystore via KeyStore.getInstance(keystore_type).

Parameters:
type - The JCE Keystore type which the PSE Membership Service should use. This value should be the name of valid JCE Keystore or null if the default Keystore type should be used.

getKeyStoreProvider

public String getKeyStoreProvider()
Return the JCE provider which the PSE Membership Service should use for Keystores. This value should be the name of valid JCE provider or null if the default provider should be used. The PSE Membership Service will create the keystore via KeyStore.getInstance(keystore_type, provider).

Returns:
The JCE provider which the PSE Membership Service should use for Keystores. This value should be the name of valid JCE provider or null if the default provider should be used.

setKeyStoreProvider

public void setKeyStoreProvider(String provider)
Set the JCE provider which the PSE Membership Service should use for Keystores. This value should be the name of valid JCE provider or null if the default provider should be used. The PSE Membership Service will create the keystore via KeyStore.getInstance(keystore_type, provider).

Parameters:
provider - The JCE provider which the PSE Membership Service should use for Keystores. This value should be the name of valid JCE provider or null if the default provider should be used.

getKeyStoreLocation

public URI getKeyStoreLocation()
Return the location of the Keystore or null if the PSE Membership Service should use the default location. The actual default location may vary depending upon they Keystore type and provider and not all location values may be valid for all Keystore types and providers.

Returns:
The location of the Keystore or null if the PSE Membership Service should use the default location.

setKeyStoreLocation

public void setKeyStoreLocation(URI location)
Set the location of the Keystore or null if the PSE Membership Service should use the default location. The actual default location may vary depending upon they Keystore type and provider and not all location values may be valid for all Keystore types and providers.

Parameters:
location - The location of the Keystore or null if the PSE Membership Service should use the default location.

setEncryptedPrivateKey

public void setEncryptedPrivateKey(String newPriv,
                                   String algorithm)
Set the encrypted private key for this advertisement. The private key is provided as a BASE64 String of a DER encoded PKCS8 EncrpytePrivateKeyInfo.

Parameters:
newPriv - a BASE64 String of a DER encoded PKCS8 EncrpytePrivateKeyInfo.
algorithm - The public key algorithm used by this private key. Currently only "RSA" is supported.

setEncryptedPrivateKey

public void setEncryptedPrivateKey(EncryptedPrivateKeyInfo newPriv,
                                   String algorithm)
Set the encrypted seed private key for this advertisement.

Parameters:
newPriv - The encrypted seed private key.
algorithm - The public key algorithm used by this private key. Currently only "RSA" is supported.

setPrivateKey

public void setPrivateKey(PrivateKey newPriv,
                          char[] password)
Set the encrypted seed private key for this advertisement.

Parameters:
password - The password to be used in encrypting the private key
newPriv - The private key to be stored in encrypted form.

handleElement

protected boolean handleElement(Element raw)
Process an individual element from the document during parse. Normally, implementations will allow the base advertisements a chance to handle the element before attempting to handle the element themselves. ie.


  protected boolean handleElement(Element elem) {

      if (super.handleElement()) {
           // it's been handled.
           return true;
           }
      ... handle elements here ...

      // we don't know how to handle the element
      return false;
      }
  

Overrides:
handleElement in class ExtendableAdvertisement
Parameters:
raw - The element to be processed.
Returns:
true if the element was recognized, otherwise false.

getDocument

public Document getDocument(MimeMediaType encodeAs)
Write this advertisement into a document of the requested type. Two standard document forms are defined. "text/plain" encodes the document in a "pretty-print" format for human viewing and "text/xml" which provides an XML format.

We don't have any content to add, just build the document instance and return it to implementations that actually do something with it.

Overrides:
getDocument in class ExtendableAdvertisement
Parameters:
encodeAs - MimeMediaType format representation requested.
Returns:
The Advertisement represented as a Document of the requested MIME Media Type.

getIndexFields

public String[] getIndexFields()
Returns the element names on which this advertisement should be indexed.

Specified by:
getIndexFields in class Advertisement
Returns:
The element names on which this advertisement should be indexed.

JXSE