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 | |
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:
-
- 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.
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:
-
String org.ccnx.ccn.io.content.WrappedKey.toString |
( |
|
) |
|
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 |
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:
-
- 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:
-
- 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:
- src/org/ccnx/ccn/io/content/WrappedKey.java