net.rim.device.api.system.PersistentContent
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public final class PersistentContent
Allows a developer to encrypt and/or compress Strings and byte arrays. Data up to (2 ^ 31) - 1 bytes
in length can be handled by this API.
This API was designed to allow applications to protect data in a database
if the user has enabled Content Protection/Compression in their device's security
settings. It consists of two main methods (encode and decode),
as well as a number of helper methods.
encode encrypts and/or compresses a String or byte array into an
encoded Object according to the device's security settings. Conversely,
decode decrypts and/or decompresses an encoded Object back
to its original form.
To encode an object:
String data = "This is a secret.";
// first compress and encrypt data
Object encoding = PersistentContent.encode( data, true, true );
... // then persist encoding
To decode an object:
try {
...
data = PersistentContent.decodeString( encoding );
...
} catch( IllegalStateException e ) {
// unable to decode data; the device must be locked.
}
Note that encoding can be performed any time, whether the device is locked or unlocked. However, an object that was encoded using encryption can only be decoded if the device is unlocked. This can pose a problem if the device locks while an application is performing a potentially long operation during which it requires the ability to decode encrypted data, such as sorting encrypted records. In this case, the application can obtain a ticket. So long as a strong reference to a ticket exists, decoding encrypted data is allowed. Thus, applications should release tickets as soon as possible to allow the device to reach a locked and secure state.
PersistentContentListener,
PersistentContentException,
PersistentStore,
PersistentObject,
RecordStore| Method Summary | ||
|---|---|---|
|
static void |
addListener(PersistentContentListener listener)
Registers a persistent content listener. |
|
static void |
addWeakListener(PersistentContentListener listener)
Registers a weak reference to a persistent content listener. |
|
static boolean |
checkEncoding(Object encoding)
Determines if provided encoding is protected under the device's current Content Protection/Compression security settings. |
|
static boolean |
checkEncoding(Object encoding,
boolean compress,
boolean encrypt)
Determines if provided encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings. |
|
static Object |
convertByteArrayToEncoding(byte[] array)
Converts a byte array back to an encoding. |
|
static byte[] |
convertEncodingToByteArray(Object encoding)
Converts a PersistentContent encoding of an object into a byte array. |
|
static Object |
copyEncoding(Object encoding)
Retrieves a copy of an encoded object. |
|
static Object |
decode(Object content)
Decodes (i.e., decrypts and/or decompresses) data. |
|
static Object |
decode(Object content,
boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of data object. |
|
static byte[] |
decodeByteArray(Object content)
Decodes (i.e., decrypts and/or decompresses) byte array. |
|
static byte[] |
decodeByteArray(Object content,
boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of byte array. |
|
static String |
decodeString(Object content)
Decodes (i.e., decrypts and/or decompresses) a string. |
|
static String |
decodeString(Object content,
boolean firstBlockOnly)
Decodes (i.e., decrypts and/or decompresses) portion of string. |
|
static Object |
encode(byte[] data)
Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device. |
|
static Object |
encode(byte[] data,
boolean compress,
boolean encrypt)
Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device. |
|
static Object |
encode(byte[] data,
int offset,
int length,
boolean compress,
boolean encrypt)
Encrypts and/or compresses a portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device. |
|
static Object |
encode(String string)
Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device. |
|
static Object |
encode(String string,
boolean compress,
boolean encrypt)
Encrypts and/or compresses a string according to the method parameters and the current Content Protection/Compression security settings on the device. |
|
static Object |
encode(String string,
int index,
int length,
boolean compress,
boolean encrypt)
Encrypts and/or compresses a sub-string according to the method parameters and the current Content Protection/Compression security settings on the device. |
|
static Object |
encodeAndAppend(byte[] data,
boolean compress,
boolean encrypt,
Object content)
Encrypts and/or compresses a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content. |
|
static Object |
encodeAndAppend(byte[] data,
int offset,
int length,
boolean compress,
boolean encrypt,
Object content)
Encrypts and/or compresses the portion of a byte array according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content. |
|
static Object |
encodeAndAppend(byte[] data,
Object content)
Encrypts and/or compresses a byte array according to the Content Protection/Compression security settings on the device, and appends it to provided content. |
|
static Object |
encodeAndAppend(String string,
boolean compress,
boolean encrypt,
Object content)
Encrypts and/or compresses string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends to provided content. |
|
static Object |
encodeAndAppend(String string,
int index,
int length,
boolean compress,
boolean encrypt,
Object content)
Encrypts and/or compresses the sub-string according to the method parameters and the current Content Protection/Compression security settings on the device, and appends it to provided content. |
|
static Object |
encodeAndAppend(String string,
Object content)
Encrypts and/or compresses a string according to the Content Protection/Compression security settings on the device, and appends to provided content. |
|
static Object |
encodeObject(Object obj)
Encrypts and/or compresses an arbitrary object according to the current Content Protection/Compression security settings on the device. |
|
static Object |
encodeObject(Object obj,
boolean compress,
boolean encrypt)
Encrypts and/or compresses an arbitrary object according to the method parameters and the current Content Protection/Compression security settings on the device. |
|
static int |
getLength(Object encoding)
Determines what the length of the encoding will be once it has been decoded. |
|
static int |
getLockGeneration()
Retrieves a counter that changes every time the user locks or unlocks their device. |
|
static int |
getModeGeneration()
Retrieves a counter that changes every time the user has changed their Content Protection settings. |
|
static int |
getState()
Retrieves the state of the device. |
|
static Object |
getTicket()
Retrieves decryption ticket. |
|
static boolean |
isByteArray(Object encoding)
Determines whether or not the provided encoding represents a byte array. |
|
static boolean |
isCompressed(Object encoding)
Determines whether or not the provided encoding is a compressed string or byte array. |
|
static boolean |
isCompressionEnabled()
Determines if Content Compression is enabled by the user. |
|
static boolean |
isContentProtectionSupported()
Determines whether or not Content Protection is supported by this device. |
|
static boolean |
isEncrypted(Object encoding)
Determines whether or not the provided encoding is an encrypted string or byte array. |
|
static boolean |
isEncryptionEnabled()
Determines if Content Encryption (i.e., Content Protection) is currently enabled by the user. |
|
static boolean |
isSecure()
Determines whether or not the device is secure, i.e., locked with no tickets held, so decoding encrypted data is not allowed. |
|
static boolean |
isString(Object encoding)
Determines whether or not the provided encoding represents a string. |
|
static boolean |
isTicketInUse()
Determines whether or not a ticket is still in use. |
|
static void |
markAsPlaintext(Object object)
Marks the provided object as plaintext (i.e., not encrypted). |
|
static Object |
reEncode(Object encoding)
Re-encodes an object according to the device's current Content Protection/Compression security settings. |
|
static Object |
reEncode(Object encoding,
boolean compress,
boolean encrypt)
Re-encodes an object according to the method parameters and the device's current Content Protection/Compression security settings. |
|
static void |
removeListener(PersistentContentListener listener)
Removes a persistent content listener. |
|
static void |
requestReEncode()
Requests that all registered PersistentContentListeners re-encode their data. |
|
static Object |
waitForTicket()
Blocks and waits to retrieve a decryption ticket. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Method Detail |
|---|
public static boolean isSecure()
public static boolean isTicketInUse()
public static boolean isContentProtectionSupported()
public static boolean isEncryptionEnabled()
public static boolean isCompressionEnabled()
public static int getModeGeneration()
The value returned by this method should be considered for comparison purposes only. That is, comparing the return value to a previously returned value lets the caller know whether the Content Protection settings have changed since the previous call. If the values are different, then the Content Protection settings have changed. This is used mainly as an optimization technique, allowing an application to abort a long encoding/decoding operation, because the Content Protection settings have changed and it will need to be done again anyway.
PersistentContentListener.persistentContentModeChanged(int)public static int getLockGeneration()
The value returned by this method should be considered for comparison purposes only. That is, comparing the return value to a previously returned value lets the caller know whether the device has locked or unlocked since the previous call. If the values are different, then the device has locked and/or unlocked. This is used mainly as an optimization technique, allowing an application to abort a long encoding/decoding operation, because the device has locked/unlocked, and it will have to be undone anyway.
PersistentContentListener.persistentContentStateChanged(int)public static int getState()
PersistentContentListenerpublic static void addListener(PersistentContentListener listener)
This method registers a strong reference to the provided listener so that it will not be garbage collected.
listener - Listener to add.public static void addWeakListener(PersistentContentListener listener)
This method registers a weak reference to the provided listener; thus, you must keep a reference to the listener to prevent it from being garbage collected.
listener - The listener to add.public static void removeListener(PersistentContentListener listener)
listener - Listener to remove.public static void requestReEncode()
PersistentContentListeners re-encode their data.
This method should be called if the application wants to enable or disable the use of encryption
on a field. For example, the user may have changed an option that requires some data to be available
in plaintext format while the device is locked. Calling requestReEncode after changing such
an option should force the required field to be re-encoded with encryption disabled, thus allowing
access to it while the device is locked.
public static void markAsPlaintext(Object object)
object - The object to be marked as plaintext.public static Object copyEncoding(Object encoding)
encoding - The encoded object to be copied.
public static Object getTicket()
If the device is currently unlocked, this method retrieves a ticket that the caller can use to decode encrypted data, for as long as the ticket is strongly referenced. This guarantees access to encrypted data even if the device locks while the caller is performing a potentially long operation, such as sorting.
Note: please release all references to the returned ticket as soon as possible, as it poses a possible security hazard if held indefinitely.
public static Object waitForTicket()
throws RuntimeException
This method behaves like PersistentContent.getTicket(), except that if the device is locked, it waits for
the device to unlock and then returns the ticket.
RuntimeException - if the calling thread is an application event threadpublic static Object encodeObject(Object obj)
obj - Object to encrypt and/or compress.
public static Object encodeObject(Object obj,
boolean compress,
boolean encrypt)
encrypt parameter must be true and Content Protection must be enabled on
the device. Note that only Strings and byte arrays are actually encoded.
An empty string or byte array cannot be encrypted.
obj - Object to encrypt and/or compress.compress - If true, this method compresses the object; otherwise, no compression performed.encrypt - If true, this method encrypts the object; otherwise, no encryption performed.
public static Object encode(String string)
string - String to encrypt and/or compress.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encode(String string,
boolean compress,
boolean encrypt)
encrypt parameter must be true and Content Protection must be enabled on the
device.
For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty string cannot be encrypted.
string - String to encrypt and/or compress.compress - If true, this method compresses string; otherwise, no compression performed.encrypt - If true, this method encrypts string; otherwise, no encryption performed.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encode(String string,
int index,
int length,
boolean compress,
boolean encrypt)
encrypt parameter must be true and Content Protection must be enabled on the
device.
For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty string cannot be encrypted.
string - String to provide source of sub-string to encrypt and/or compress.index - First character in string to encrypt and/or compress.length - Number of characters from string to encrypt and/or compress (-1 means the rest of the string).compress - If true, this method compresses sub-string; otherwise, no compression performed.encrypt - If true, this method encrypts sub-string; otherwise, no encryption performed.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(String string,
Object content)
string - String to encrypt and/or compress.content - Content object to which to append encrypted and/or compressed string.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(String string,
boolean compress,
boolean encrypt,
Object content)
encrypt parameter must be true and Content
Protection must be enabled on the device. An empty string cannot be encrypted.
string - String to encrypt and/or compress.compress - If true, this method compresses string; otherwise, no compression performed.encrypt - If true, this method encrypts string; otherwise, no encryption performed.content - Content object to which to append encrypted and/or compressed string.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(String string,
int index,
int length,
boolean compress,
boolean encrypt,
Object content)
encrypt parameter must be true and Content
Protection must be enabled on the device.
string - the string containing the sub-string to encrypt and/or compressindex - the first character in string to encrypt and/or compresslength - the number of characters from string to encrypt and/or compress; -1 means
the rest of stringcompress - if true compression is performedencrypt - if true encryption is performedcontent - a, possibly null, object to which to append the newly encrypted and/or compressed
sub-string; must be an instance of String or char[]
content if string is null;
an empty String if length is 0 and content is null;
a new char[] containing the encoded data if content is null;
or output with the newly encoded data appended to it
IllegalArgumentException - if an illegal or inappropriate argument has been specifiedpublic static Object encode(byte[] data)
data - Data to encrypt and/or compress.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encode(byte[] data,
boolean compress,
boolean encrypt)
encrypt parameter must be true and Content Protection must be enabled on the
device.
For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty byte array cannot be encrypted.
data - Data to encrypt and/or compress.compress - If true, this method compresses data; otherwise, no compression performed.encrypt - If true, this method encrypts data; otheriwse, no encryption performed.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encode(byte[] data,
int offset,
int length,
boolean compress,
boolean encrypt)
encrypt parameter must be true and Content Protection must be enabled on
the device.
For an object to be compressed, its size must be greater than or equal to 32 bytes. An empty byte array cannot be encrypted.
data - Data to encrypt and/or compress.offset - First byte in data to encrypt and/or compress.length - Number of bytes from data to encrypt and/or compress (-1 means the rest of the array).compress - If true, this method compresses data; otherwise, no compression performed.encrypt - If true, this method encrypts data; otherwise, no encryption performed.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(byte[] data,
Object content)
data - Data to encrypt and/or compress.content - Content object to which to append encrypted and/or compressed data.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(byte[] data,
boolean compress,
boolean encrypt,
Object content)
encrypt parameter must be true and Content
Protection must be enabled on the device. An empty byte array cannot be encrypted.
data - Data to encrypt and/or compress.compress - If true, this method compresses data; otherwise, no compression performed.encrypt - If true, this method encrypts data; otherwise, no encryption performed.content - Content object to which to append encrypted and/or compressed data.
IllegalArgumentException - if the data to be encoded is larger that what is supported by Content Protection
public static Object encodeAndAppend(byte[] data,
int offset,
int length,
boolean compress,
boolean encrypt,
Object content)
encrypt parameter must be true and Content
Protection must be enabled on the device.
data - the buffer containing the data to encrypt and/or compressoffset - first byte in data to encrypt and/or compresslength - number of bytes from data to encrypt and/or compress;
-1 means the rest of the arraycompress - if true this method compresses data; otherwise, no compression is performedencrypt - if true this method encrypts data; otherwise, no encryption performedcontent - a, possibly null object to which to append encrypted and/or compressed data; must be
an instance of byte[] or char[]
content if data is null;
an empty byte[] if length is 0 and null;
a new char[] containing the encoded data if content is null;
or output with the newly encoded data appended to it
IllegalArgumentException - if an illegal or inappropriate argument has been specifiedpublic static Object decode(Object content)
content - Data object to decode.
public static String decodeString(Object content)
content - Data object to decode.
ClassCastException - thrown if the decoded object is not a String.
public static String decodeString(Object content,
boolean firstBlockOnly)
content - Data object to decode.firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
ClassCastException - thrown if the decoded object is not a String.public static byte[] decodeByteArray(Object content)
content - Data object to decode.
ClassCastException - thrown if the decoded object is not a byte array.
public static byte[] decodeByteArray(Object content,
boolean firstBlockOnly)
content - Data object to decode.firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
ClassCastException - thrown if the decoded object is not a byte array.
public static Object decode(Object content,
boolean firstBlockOnly)
content - Data object to decode.firstBlockOnly - If true, decode only first block of data; otherwise, decode entire data object.
public static boolean isCompressed(Object encoding)
encoding - Encoding to test.
public static boolean isEncrypted(Object encoding)
encoding - Encoding to test.
public static boolean isString(Object encoding)
encoding - Encoding to test.
public static boolean isByteArray(Object encoding)
encoding - Encoding to test.
public static int getLength(Object encoding)
If encoding is actually a string, then this method just returns String.length(). If encoding
is actually a byte array, then this method just returns the number of byte elements in the array.
encoding - Encoding to measure.
public static boolean checkEncoding(Object encoding)
Use this method to determine if the provided encoding is protected under the device's current Content Protection/Compression security settings. If not, the encoding should be re-encoded.
encoding - Encoding to check.
PersistentContent.reEncode(java.lang.Object).
public static boolean checkEncoding(Object encoding,
boolean compress,
boolean encrypt)
encrypt
parameter is true and Content Protection is enabled on the device, this method verifies that the
encoding is encrypted.
Use this method to determine if the provided encoding is protected according to the method parameters and the device's current Content Protection/Compression security settings. If not, the encoding should be re-encoded.
encoding - Encoding to check.compress - Compression setting to use.encrypt - Encryption setting to use.
PersistentContent.reEncode(java.lang.Object).public static Object reEncode(Object encoding)
encoding - Encoding to re-encode.
public static Object reEncode(Object encoding,
boolean compress,
boolean encrypt)
encrypt parameter is true and Content Protection is
enabled on the device, this method ensures that the encoding is encrypted.
encoding - Encoding to re-encode.compress - Compression setting to use.encrypt - Encryption setting to use.
public static byte[] convertEncodingToByteArray(Object encoding)
This method can be used to serialize an encoded object to a byte array, e.g., for storage in an RMS database, or to ensure that backed up data can only be restored to the same device.
encoding - Encoding to convert.
PersistentContent.convertByteArrayToEncoding(byte[])public static Object convertByteArrayToEncoding(byte[] array)
array - Byte array that contains an encoding, as returned by
PersistentContent.convertEncodingToByteArray(java.lang.Object).
PersistentContent.decode(java.lang.Object).
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.