net.rim.device.api.crypto
Class CryptoSmartCardSession

java.lang.Object
  extended by net.rim.device.api.smartcard.SmartCardSession
      extended by net.rim.device.api.crypto.CryptoSmartCardSession

public abstract class CryptoSmartCardSession
extends SmartCardSession

The CryptoSmartCardSession class should be extended by all cryptographic smart cards.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

Field Summary
 
Fields inherited from class net.rim.device.api.smartcard.SmartCardSession
DECRYPT_OPERATION, FINGERPRINT_CONTEXT_AUTHENTICATION, INS_APPEND_RECORD, INS_ENVELOPE, INS_ERASE_BINARY, INS_EXTERNAL_AUTHENTICATE, INS_GET_CHALLENGE, INS_GET_DATA, INS_GET_RESPONSE, INS_INTERNAL_AUTHENTICATE, INS_MANAGE_CHANNEL, INS_PUT_DATA, INS_READ_BINARY, INS_READ_RECORD, INS_SELECT_FILE, INS_UPDATE_BINARY, INS_UPDATE_RECORD, INS_VERIFY, INS_WRITE_BINARY, INS_WRITE_RECORD, KEY_GENERATION_OPERATION, NON_CRYPTO_OPERATION, SIGN_OPERATION, UNKNOWN_OPERATION, USER_AUTHENTICATION_OPERATION
 
Constructor Summary
Category: Signed protected CryptoSmartCardSession(SmartCard smartCard, SmartCardReaderSession readerSession)
          Constructs a new CryptoSmartCardSession object.
 
Method Summary
Category: Signed protected  void dismissProgressDialog()
          Closes the progress bar.
Category: Signed protected  void displayProgressDialog(String title, int numSteps)
          Displays a progress dialog.
Category: Signed  CryptoSmartCardKeyStoreData[] getKeyStoreDataArray()
          Returns an array of KeyStoreData associated with the keys stored on the card.
Category: Signed  CryptoSmartCardKeyStoreData[] getKeyStoreDataArray(boolean allowCancel)
          Returns an array of KeyStoreData associated with the keys stored on the card.
Category: Signed protected abstract  CryptoSmartCardKeyStoreData[] getKeyStoreDataArrayImpl()
          Returns an array of KeyStoreData associated with the keys stored on the card.
Category: Signed protected  CryptoSmartCardKeyStoreData[] getKeyStoreDataArrayImpl(boolean allowCancel)
          Returns an array of KeyStoreData associated with the keys stored on the card.
Category: Signed  void getRandomBytes(byte[] buffer)
          Generates random bytes, filling the given buffer entirely.
Category: Signed  void getRandomBytes(byte[] buffer, int offset, int length)
          Inserts random bytes into the given buffer starting at the specified array index offset.
Category: Signed  byte[] getRandomBytes(int length)
          Generates a specified length of random bytes, returning them as a byte array of the specified size.
Category: Signed protected abstract  byte[] getRandomBytesImpl(int maxNumBytes)
          Returns random bytes of data from the smart cards internal RNG.
Category: Signed protected  void setProgressDialog(int value)
          Sets the progress bar at a particular value.
Category: Signed protected  void stepProgressDialog(int delta)
          Increments the progress bar.
 
Methods inherited from class net.rim.device.api.smartcard.SmartCardSession
close, closeImpl, getFingerprints, getFingerprintsImpl, getMaxLoginAttempts, getMaxLoginAttemptsImpl, getRemainingLoginAttempts, getRemainingLoginAttemptsImpl, getSmartCard, getSmartCardID, getSmartCardIDImpl, getSmartCardReaderSession, isLoggedIn, isOpen, login, loginImpl, loginPrompt, sendAPDU
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

CryptoSmartCardSession

protected CryptoSmartCardSession(SmartCard smartCard,
                                 SmartCardReaderSession readerSession)
Constructs a new CryptoSmartCardSession object.

Parameters:
smartCard - The SmartCard to use.
readerSession - The SmartCardReaderSession to use.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0


Method Detail

getKeyStoreDataArray

public final CryptoSmartCardKeyStoreData[] getKeyStoreDataArray()
                                                         throws SmartCardException,
                                                                CryptoTokenException
Returns an array of KeyStoreData associated with the keys stored on the card.

Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
CryptoTokenException - Thrown if there is a token related problem.
SmartCardSessionClosedException - Thrown if this session is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getKeyStoreDataArray

public final CryptoSmartCardKeyStoreData[] getKeyStoreDataArray(boolean allowCancel)
                                                         throws SmartCardException,
                                                                CryptoTokenException
Returns an array of KeyStoreData associated with the keys stored on the card.

Parameters:
allowCancel - true if the user is allowed to cancel the operation
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
CryptoTokenException - Thrown if there is a token related problem.
SmartCardSessionClosedException - Thrown if this session is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

getKeyStoreDataArrayImpl

protected abstract CryptoSmartCardKeyStoreData[] getKeyStoreDataArrayImpl()
                                                                   throws SmartCardException,
                                                                          CryptoTokenException
Returns an array of KeyStoreData associated with the keys stored on the card.

The array should contain all the private keys (or references to), symmetric keys (or references to), public keys and certificates on the card.

If a KeyStoreData contains public keys, they must be valid PublicKeys. Public key cryptographic operations will be handled by the device and not by the smartcard.

If the key store contains certificates, they must be valid Certificates.

Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
CryptoTokenException - Thrown if there is a token related problem.
SmartCardSessionClosedException - Thrown if this session is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getKeyStoreDataArrayImpl

protected CryptoSmartCardKeyStoreData[] getKeyStoreDataArrayImpl(boolean allowCancel)
                                                          throws SmartCardException,
                                                                 CryptoTokenException
Returns an array of KeyStoreData associated with the keys stored on the card.

The array should contain all the private keys (or references to), symmetric keys (or references to), public keys and certificates on the card.

If a KeyStoreData contains public keys, they must be valid PublicKeys. Public key cryptographic operations will be handled by the device and not by the smartcard.

If the key store contains certificates, they must be valid Certificates.

The default behaviour of this method is equivalent to CryptoSmartCardSession.getKeyStoreDataArrayImpl() with the allowCancel parameter being ignored.

Parameters:
allowCancel - true if the user is allowed to cancel the operation
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
CryptoTokenException - Thrown if there is a token related problem.
SmartCardSessionClosedException - Thrown if this session is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

displayProgressDialog

protected void displayProgressDialog(String title,
                                     int numSteps)
Displays a progress dialog. This method can be used by subclasses during long operations, such as getKeyStoreDataArrayImpl(), to indicate progress to the user. If a progress dialog is currently displayed, then it is dismissed and the new dialog is displayed.

Note: Be sure to call dismissProgressDialog().

Parameters:
title - A short String to describe the operation
numSteps - The maximum number of steps to be performed
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

stepProgressDialog

protected void stepProgressDialog(int delta)
Increments the progress bar.

Parameters:
delta - The number of steps to increment the progress bar.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

setProgressDialog

protected void setProgressDialog(int value)
Sets the progress bar at a particular value.

Parameters:
value - The new value of the progress bar.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

dismissProgressDialog

protected void dismissProgressDialog()
Closes the progress bar.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getRandomBytes

public final void getRandomBytes(byte[] buffer,
                                 int offset,
                                 int length)
                          throws SmartCardException
Inserts random bytes into the given buffer starting at the specified array index offset.

Parameters:
buffer - The buffer to store the random bytes. Must be non-null.
offset - The start, or initial position, of the data within the buffer.
length - The number of random bytes to store.
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
SmartCardSessionClosedException - Thrown if this session is closed.
SmartCardUnsupportedOperationException - Thrown if the card does not support returning random bytes
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getRandomBytes

public final byte[] getRandomBytes(int length)
                            throws SmartCardException
Generates a specified length of random bytes, returning them as a byte array of the specified size.

Parameters:
length - The number of random bytes to generate.
Returns:
A byte array containing the random bytes.
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
SmartCardSessionClosedException - Thrown if this session is closed.
SmartCardUnsupportedOperationException - Thrown if the card does not support returning random bytes
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getRandomBytes

public final void getRandomBytes(byte[] buffer)
                          throws SmartCardException
Generates random bytes, filling the given buffer entirely.

Parameters:
buffer - The byte array to fill with random bytes. Must be non-null.
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
SmartCardSessionClosedException - Thrown if this session is closed.
SmartCardUnsupportedOperationException - Thrown if the card does not support returning random bytes
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0

getRandomBytesImpl

protected abstract byte[] getRandomBytesImpl(int maxNumBytes)
                                      throws SmartCardException
Returns random bytes of data from the smart cards internal RNG. The number of bytes returned should be less than or equal to maxNumBytes. The calling methods will take care of calling this method until the correct number of bytes are retrieved.

Parameters:
maxNumBytes - The maximum number of random bytes to retrieve. The value will be greater than zero.
Returns:
The random bytes. The number of bytes returned may be less than numBytes.
Throws:
SmartCardException - Thrown if an error occurs when communicating with the smart card.
SmartCardSessionClosedException - Thrown if this session is closed.
SmartCardUnsupportedOperationException - Thrown if the card does not support returning random bytes
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.1.0





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.