org.ccnx.ccn.io.content.WrappedKey Class Reference

A representation of wrapped (encrypted) keys for strorage in CCN. More...

List of all members.

Classes

class  WrappedKeyObject
 A CCNNetworkObject wrapper around WrappedKey, used for easily saving and retrieving versioned WrappedKeys to CCN. More...

Public Member Functions

 WrappedKey (byte[] wrappingKeyIdentifier, byte[] encryptedKey)
 Represent an already-wrapped key as a WrappedKey.
 WrappedKey (byte[] wrappingKeyIdentifier, String label, byte[] encryptedKey)
 Represent an already-wrapped key as a WrappedKey.
 WrappedKey (byte[] wrappingKeyIdentifier, String wrapAlgorithm, String keyAlgorithm, String label, byte[] encryptedKey)
 Represent an already-wrapped key as a WrappedKey.
 WrappedKey (byte[] wrappingKeyIdentifier, String wrapAlgorithm, String keyAlgorithm, String label, byte[] encryptedNonceKey, byte[] encryptedKey)
 Represent an already-wrapped key as a WrappedKey.
 WrappedKey ()
 Empty constructor for decoding.
Key unwrapKey (Key unwrapKey) throws InvalidKeyException, NoSuchAlgorithmException
 Unwraps an encrypted key, and decodes it into a Key of an algorithm type specified by keyAlgorithm().
Key unwrapKey (Key unwrapKey, String wrappedKeyAlgorithm) throws InvalidKeyException, NoSuchAlgorithmException
 Unwraps an encrypted key, and decodes it into a Key of an algorithm type specified by wrappedKeyAlgorithm.
byte[] wrappingKeyIdentifier ()
void setWrappingKeyIdentifier (byte[] wrappingKeyIdentifier)
 Sets the wrappingKeyIdentifier.
void setWrappingKeyIdentifier (Key wrappingKey)
 Sets the wrappingKeyIdentifier.
ContentName wrappingKeyName ()
void setWrappingKeyName (ContentName keyName)
 Set the wrappingKeyName.
String wrapAlgorithm ()
 Returns the wrapping algorithm identifier, if specified.
String keyAlgorithm ()
 Returns the key algorithm identifier, if specified.
String label ()
 Returns the label if we have one.
byte[] encryptedNonceKey ()
 Returns the encrypted nonce key if we have one.
byte[] encryptedKey ()
 Get the encrypted key.
void decode (XMLDecoder decoder) throws ContentDecodingException
 Decode this object as the top-level item in a new XML document, reading it from a network buffer.
void encode (XMLEncoder encoder) throws ContentEncodingException
 Encode this object during an ongoing encoding pass; this is what subclasses generally need to know how to implement.
long getElementLabel ()
 Allow the encoder/decoder to retrieve the top-level element name programmatically.
boolean validate ()
 Make sure all of the necessary fields are filled in prior to attempting to encode.
int hashCode ()
boolean equals (Object obj)
String toString ()
 Default toString() implementation simply prints the text encoding of the object.

Static Public Member Functions

static WrappedKey wrapKey (Key keyToBeWrapped, String keyAlgorithm, String keyLabel, Key wrappingKey) throws InvalidKeyException
 Wraps a {symmetric, private} key in another {symmetric, public} key, using standard wrap algorithm.
static byte[] wrappingKeyIdentifier (Key wrappingKey)
 Calculate the wrappingKeyIdentifier corresponding to this key.
static int getCipherType (String cipherAlgorithm)
static String wrapAlgorithmForKey (String keyAlgorithm)
 Convert a given wrapping key algorithm to the default wrap algorithm for using that key.
static Key generateNonceKey ()

Static Protected Member Functions

static byte[] AESWrapWithPad (Key wrappingKey, Key keyToBeWrapped) throws InvalidKeyException, IllegalBlockSizeException
 Wrap using AES.
static Key AESUnwrapWithPad (Key unwrappingKey, String wrappedKeyAlgorithm, byte[] input, int offset, int length) throws InvalidKeyException
 Unwrap using AES.

Static Protected Attributes

static final String NONCE_KEY_ALGORITHM = "AES"
static final int NONCE_KEY_LENGTH = 128

Static Package Functions

 [static initializer]

Package Attributes

byte[] _wrappingKeyIdentifier
WrappingKeyName _wrappingKeyName
String _wrapAlgorithm
String _keyAlgorithm
String _label
byte[] _encryptedNonceKey
byte[] _encryptedKey

Detailed Description

A representation of wrapped (encrypted) keys for strorage in CCN.

These are used to transfer symmetric and private keys between users, store them for backup, do key distribution for access control, and so on. They use standard key wrapping algorithms, and try to be fairly general. You can use them to wrap almost any type of key in any other type of key (as long as the latter is capable of encryption), though use of this class with some key types or key lengths may require installation of the Java unlimited strength cryptography policy files to succeed.

This class automatically handles generation of interstitial nonce keys for wrapping keys of incompatible lengths -- if you want to wrap a private key in another private key, it will generate a nonce key, wrap the first key in that nonce key, and that nonce key in the second private key.

For now, we have a very loose definition of default -- the default wrap algorithm depends on the type of key being used to wrap; similarly the default key algorithm depends on the type of the key being wrapped. We assume that the wrapper and unwrapper usually know the type of the wrapping key, and can derive the wrapAlgorithm. The keyAlgorithm is more often necessary to determine how to decode the key once unwrapped so it is more frequently present. Both are optional.

If the caller does not specify a wrapping algorithm, a standards-based default is selected, see documentation for details.

If the caller specifies values they will be encoded on the wire and decoded on the other end; defaults will not currently be enforced automatically. This means equals behavior should be watched closely.


Constructor & Destructor Documentation

org.ccnx.ccn.io.content.WrappedKey.WrappedKey ( byte[]  wrappingKeyIdentifier,
byte[]  encryptedKey 
)

Represent an already-wrapped key as a WrappedKey.

Parameters:
wrappingKeyIdentifier a byte ID for this key, usually the digest of the encoded key.
encryptedKey the wrapped, encoded key.
org.ccnx.ccn.io.content.WrappedKey.WrappedKey ( byte[]  wrappingKeyIdentifier,
String  label,
byte[]  encryptedKey 
)

Represent an already-wrapped key as a WrappedKey.

Parameters:
wrappingKeyIdentifier a byte ID for this key, usually the digest of the encoded key.
label a friendly name for the key.
encryptedKey the wrapped, encoded key.
org.ccnx.ccn.io.content.WrappedKey.WrappedKey ( byte[]  wrappingKeyIdentifier,
String  wrapAlgorithm,
String  keyAlgorithm,
String  label,
byte[]  encryptedKey 
)

Represent an already-wrapped key as a WrappedKey.

Parameters:
wrappingKeyIdentifier a byte ID for this key, usually the digest of the encoded key.
wrapAlgorithm the algorithm used to wrap this key, if null the default wrap algorithm for the decryption key (specified to unwrapKey()) is used
keyAlgorithm the algorithm of the wrapped (encrypted, encoded) key. Necessary to decode the key back into a Key object as part of unwrapping. Can be specified at unwrapping time if not stored here.
label a friendly name for the key.
encryptedKey the wrapped, encoded key.
org.ccnx.ccn.io.content.WrappedKey.WrappedKey ( byte[]  wrappingKeyIdentifier,
String  wrapAlgorithm,
String  keyAlgorithm,
String  label,
byte[]  encryptedNonceKey,
byte[]  encryptedKey 
)

Represent an already-wrapped key as a WrappedKey.

Parameters:
wrappingKeyIdentifier a byte ID for this key, usually the digest of the encoded key.
wrapAlgorithm the algorithm used to wrap this key, if null the default wrap algorithm for the decryption key (specified to unwrapKey()) is used
keyAlgorithm the algorithm of the wrapped (encrypted, encoded) key. Necessary to decode the key back into a Key object as part of unwrapping. Can be specified at unwrapping time if not stored here.
label a friendly name for the key.
encryptedNonceKey if the key is a private or public key wrapped by a public key, this defines an encrypted interposed nonce key where the nonce key is used to wrap the private or public key and the wrapping key is used to wrap the nonce key.
encryptedKey the wrapped, encoded key.

Member Function Documentation

static Key org.ccnx.ccn.io.content.WrappedKey.AESUnwrapWithPad ( Key  unwrappingKey,
String  wrappedKeyAlgorithm,
byte[]  input,
int  offset,
int  length 
) throws InvalidKeyException [static, protected]

Unwrap using AES.

Do not use standard Cipher interface, as we need to use an alternate algorithm (see AESWrapWithPadEngine) that is not currently included in any signed provider. Once it is, we will drop this special-case code.

Parameters:
unwrappingKey key to use to decrypt
wrappedKeyAlgorithm algorithm to use to decode key once decrypted.
input encrypted key to decrypt and decode
offset offset into encrypted data buffer
length length of data to decrypt.
Returns:
decrypted, decoded key.
static byte [] org.ccnx.ccn.io.content.WrappedKey.AESWrapWithPad ( Key  wrappingKey,
Key  keyToBeWrapped 
) throws InvalidKeyException, IllegalBlockSizeException [static, protected]

Wrap using AES.

Do not use standard Cipher interface, as we need to use an alternate algorithm (see AESWrapWithPadEngine) that is not currently included in any signed provider. Once it is, we will drop this special-case code.

Parameters:
wrappingKey key to use to encrypt
keyToBeWrapped key to encrypt
Returns:
encrypted key.
Exceptions:
IllegalBlockSizeException 
InvalidKeyException 
void org.ccnx.ccn.io.content.WrappedKey.decode ( XMLDecoder  decoder  )  throws ContentDecodingException [virtual]

Decode this object as the top-level item in a new XML document, reading it from a network buffer.

Reads document start and end. Assumes default encoding.

Parameters:
buf input stream to read from
Exceptions:
ContentDecodingException if there is an error decoding the content Decode this object as the top-level item in a new XML document, reading it from a network buffer. Reads document start and end.
Parameters:
buf input stream to read from
codec the codec to use; must be recognized by XMLCodecFactory
Exceptions:
ContentDecodingException if there is an error decoding the content
See also:
XMLCodecFactory Decode this object during an ongoing decoding pass; this is what subclasses generally need to know how to implement. Reads just the object itself, higher-level processes have handled start and end document if need be. Allows object to be read using the same code whether it is a top-level element written alone, or nested inside another element.
Parameters:
decoder the decoder being used; encapsulates state including the codec being used as well as the input source and current offset

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

void org.ccnx.ccn.io.content.WrappedKey.encode ( XMLEncoder  encoder  )  throws ContentEncodingException [virtual]

Encode this object during an ongoing encoding pass; this is what subclasses generally need to know how to implement.

Writes just the object itself, higher-level processes have handled start and end document if need be. Allows object to be written using the same code whether it is a top-level element written alone, or nested inside another element.

Parameters:
encoder the encoder being used; encapsulates state including the codec being used as well as the output destination and current offset

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

byte [] org.ccnx.ccn.io.content.WrappedKey.encryptedKey (  ) 

Get the encrypted key.

Returns:
the encrypted key
byte [] org.ccnx.ccn.io.content.WrappedKey.encryptedNonceKey (  ) 

Returns the encrypted nonce key if we have one.

Returns:
the encryptedNonceKey, if one is present
long org.ccnx.ccn.io.content.WrappedKey.getElementLabel (  )  [virtual]

Allow the encoder/decoder to retrieve the top-level element name programmatically.

This allows subclasses to rename elements without changing their encoder/decoders.

Returns:
the element label to use, as a key in a loaded encoding dictionary

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

String org.ccnx.ccn.io.content.WrappedKey.keyAlgorithm (  ) 

Returns the key algorithm identifier, if specified.

Returns:
the key algorithm
String org.ccnx.ccn.io.content.WrappedKey.label (  ) 

Returns the label if we have one.

Returns:
the label
void org.ccnx.ccn.io.content.WrappedKey.setWrappingKeyIdentifier ( Key  wrappingKey  ) 

Sets the wrappingKeyIdentifier.

Parameters:
wrappingKey key from which to generate the new identifier
void org.ccnx.ccn.io.content.WrappedKey.setWrappingKeyIdentifier ( byte[]  wrappingKeyIdentifier  ) 

Sets the wrappingKeyIdentifier.

Parameters:
wrappingKeyIdentifier new identifier
void org.ccnx.ccn.io.content.WrappedKey.setWrappingKeyName ( ContentName  keyName  ) 

Set the wrappingKeyName.

Parameters:
keyName the new name
String org.ccnx.ccn.io.content.WrappedKey.toString (  ) 

Default toString() implementation simply prints the text encoding of the object.

This demonstrates how to force use of the text encoding.

Reimplemented from org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

Key org.ccnx.ccn.io.content.WrappedKey.unwrapKey ( Key  unwrapKey,
String  wrappedKeyAlgorithm 
) throws InvalidKeyException, NoSuchAlgorithmException

Unwraps an encrypted key, and decodes it into a Key of an algorithm type specified by wrappedKeyAlgorithm.

Parameters:
unwrapKey the key to use to decrypt this wrapped key.
wrappedKeyAlgorithm the algorithm of the wrapped key, used in decoding it.
Returns:
the decrypted key if successful.
Exceptions:
InvalidKeyException if we encounter an error using the unwrapKey to decrypt.
NoSuchAlgorithmException if we do not recognize the wrappedKeyAlgorithm.
Key org.ccnx.ccn.io.content.WrappedKey.unwrapKey ( Key  unwrapKey  )  throws InvalidKeyException, NoSuchAlgorithmException

Unwraps an encrypted key, and decodes it into a Key of an algorithm type specified by keyAlgorithm().

See unwrapKey(Key, String) for details.

Exceptions:
NoSuchAlgorithmException 
@see unwrapKey(Key, String)
boolean org.ccnx.ccn.io.content.WrappedKey.validate (  )  [virtual]

Make sure all of the necessary fields are filled in prior to attempting to encode.

All implementations of encode(XMLEncoder) should call this for their classes prior to encoding.

Returns:
true if object is valid and can be encoded, false if there is a problem; for example mandatory fields are uninitialized

Implements org.ccnx.ccn.impl.encoding.GenericXMLEncodable.

String org.ccnx.ccn.io.content.WrappedKey.wrapAlgorithm (  ) 

Returns the wrapping algorithm identifier, if specified.

Returns:
the wrap algorithm
static String org.ccnx.ccn.io.content.WrappedKey.wrapAlgorithmForKey ( String  keyAlgorithm  )  [static]

Convert a given wrapping key algorithm to the default wrap algorithm for using that key.

Parameters:
keyAlgorithm 
Returns:
static WrappedKey org.ccnx.ccn.io.content.WrappedKey.wrapKey ( Key  keyToBeWrapped,
String  keyAlgorithm,
String  keyLabel,
Key  wrappingKey 
) throws InvalidKeyException [static]

Wraps a {symmetric, private} key in another {symmetric, public} key, using standard wrap algorithm.

Does not include an identifier of the wrapping key; that can be added if necessary using setWrappingKeyIdentifier(Key). Default wrap algorithm if wrapping key is AES is AESWrap (RFC3394, NIST standard); this is available in Java 1.6, or BouncyCastle.

Parameters:
keyToBeWrapped The key to wrap, can be symmetric, private, or public.
keyAlgorithm optional algorithm to associate with the wrapped key; if null we use key.getAlgorithm().
keyLabel a friendly name for the key.
wrappingKey The key to use for wrapping. This can be a symmetric key or a public key (as noted above, some public key algorithms may require Java's unlimited strength policy files). If the wrapping key is a public key, and the wrapped key is a private key (which may extend past the block length of the public key) we will automatically generate a nonce (random) AES key, wrap the private key in that, and then wrap that nonce key in the public key. We derive the wrapping algorithm to use as a function of this key's algorithm. Eventually may want to allow it to be passed in (merely encrypting with the key as usual may not be the best key wrap algorithm; keys are high entropy and often require specialized padding schemes).
Exceptions:
NoSuchPaddingException 
NoSuchAlgorithmException 
InvalidKeyException 
IllegalBlockSizeException 
static byte [] org.ccnx.ccn.io.content.WrappedKey.wrappingKeyIdentifier ( Key  wrappingKey  )  [static]

Calculate the wrappingKeyIdentifier corresponding to this key.

Parameters:
wrappingKey the key
Returns:
the identifier
byte [] org.ccnx.ccn.io.content.WrappedKey.wrappingKeyIdentifier (  ) 
Returns:
the wrappingKeyIdentfier for this object
ContentName org.ccnx.ccn.io.content.WrappedKey.wrappingKeyName (  ) 
Returns:
the wrappingKeyName if specified

The documentation for this class was generated from the following file:
Generated on Fri May 13 16:27:46 2011 for Content-Centric Networking in Java by  doxygen 1.6.3