A SmartCardSession represents a communications session with a physical smartcard.
Over this session, APDUs may be exchanged with the smartcard to provide the desired functionality. Subclasses may provide
additional functions.
Sessions should not be held open when not in use. As a security precaution, only one open session is allowed to exist per SmartCardReader,
and subsequent openSession requests will block until the current session is closed.
Note to implementors: Most, if not all, UI functionality has been implemented in the base class.
Typically, subclasses should not need to implement any UI.
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.
INS_PUT_DATA
Put Data INS code as defined by ISO/IEC 7816-4
static byte
INS_READ_BINARY
Read Binary INS code as defined by ISO/IEC 7816-4
static byte
INS_READ_RECORD
Read Record INS code as defined by ISO/IEC 7816-4
static byte
INS_SELECT_FILE
Select File INS code as defined by ISO/IEC 7816-4
static byte
INS_UPDATE_BINARY
Update Binary INS code as defined by ISO/IEC 7816-4
static byte
INS_UPDATE_RECORD
Update Record INS code as defined by ISO/IEC 7816-4
static byte
INS_VERIFY
Verify INS code as defined by ISO/IEC 7816-4
static byte
INS_WRITE_BINARY
Write Binary INS code as defined by ISO/IEC 7816-4
static byte
INS_WRITE_RECORD
Write Record INS code as defined by ISO/IEC 7816-4
static int
KEY_GENERATION_OPERATION
Indicates that this session will be used for a user key generation operation
static int
NON_CRYPTO_OPERATION
Indicates that this session will be used for a non-cryptographic operation, for example, importing the certificates off the smartcard.
static int
SIGN_OPERATION
Indicates that this session will be used for a signing operation
static int
UNKNOWN_OPERATION
Indicates that this session will be used for a unknown operation
close()
Closes the session, and the underlying SmartCardReaderSession.
protected abstract void
closeImpl()
Closes the session with the smartcard.
int
getMaxLoginAttempts()
Returns the maximum number of login attempts allowed, or
Integer.MAX_VALUE if an infinite number of attempts are allowed.
protected abstract int
getMaxLoginAttemptsImpl()
Returns the maximum number of login attempts allowed, or
Integer.MAX_VALUE if an infinite number of attempts are allowed.
int
getRemainingLoginAttempts()
Returns the remaining number of login attempts allowed before the smartcard will lock,
or Integer.MAX_VALUE if the smartcard will not lock.
protected abstract int
getRemainingLoginAttemptsImpl()
Returns the remaining number of login attempts allowed before the smartcard will lock,
or Integer.MAX_VALUE if the smart card will not lock.
Indicates that this session will be used for a decryption operation
Since:
JDE 4.1.0
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.
INS_APPEND_RECORD
public static final byte INS_APPEND_RECORD
Append Record INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_ENVELOPE
public static final byte INS_ENVELOPE
Envelope INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_ERASE_BINARY
public static final byte INS_ERASE_BINARY
Erase Binary INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_EXTERNAL_AUTHENTICATE
public static final byte INS_EXTERNAL_AUTHENTICATE
External Authenticate INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_GET_CHALLENGE
public static final byte INS_GET_CHALLENGE
Get Challenge INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_GET_DATA
public static final byte INS_GET_DATA
Get Data INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_GET_RESPONSE
public static final byte INS_GET_RESPONSE
Get Response INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_INTERNAL_AUTHENTICATE
public static final byte INS_INTERNAL_AUTHENTICATE
Internal Authenticate INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_MANAGE_CHANNEL
public static final byte INS_MANAGE_CHANNEL
Manage Channel INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_PUT_DATA
public static final byte INS_PUT_DATA
Put Data INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_READ_BINARY
public static final byte INS_READ_BINARY
Read Binary INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_READ_RECORD
public static final byte INS_READ_RECORD
Read Record INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_SELECT_FILE
public static final byte INS_SELECT_FILE
Select File INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_UPDATE_BINARY
public static final byte INS_UPDATE_BINARY
Update Binary INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_UPDATE_RECORD
public static final byte INS_UPDATE_RECORD
Update Record INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_VERIFY
public static final byte INS_VERIFY
Verify INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_WRITE_BINARY
public static final byte INS_WRITE_BINARY
Write Binary INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
INS_WRITE_RECORD
public static final byte INS_WRITE_RECORD
Write Record INS code as defined by ISO/IEC 7816-4
Since:
4.1.1
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.
KEY_GENERATION_OPERATION
public static final int KEY_GENERATION_OPERATION
Indicates that this session will be used for a user key generation operation
Since:
JDE 4.1.0
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.
NON_CRYPTO_OPERATION
public static final int NON_CRYPTO_OPERATION
Indicates that this session will be used for a non-cryptographic operation, for example, importing the certificates off the smartcard.
Since:
JDE 4.1.0
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.
SIGN_OPERATION
public static final int SIGN_OPERATION
Indicates that this session will be used for a signing operation
Since:
JDE 4.1.0
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.
UNKNOWN_OPERATION
public static final int UNKNOWN_OPERATION
Indicates that this session will be used for a unknown operation
Since:
JDE 4.1.0
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.
USER_AUTHENTICATION_OPERATION
public static final int USER_AUTHENTICATION_OPERATION
Indicates that this session will be used for a user authentication operation
Since:
JDE 4.1.0
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.
smartCard - The SmartCard object associated with this session.
readerSession - The underlying reader session.
Since:
JDE 4.1.0
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.
Method Detail
close
public final void close()
Closes the session, and the underlying SmartCardReaderSession.
Sessions should be closed promptly when no longer needed.
Since:
JDE 4.1.0
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.
closeImpl
protected abstract void closeImpl()
Closes the session with the smartcard.
Implementations should not close the underlying SmartCardReaderSession.
Since:
JDE 4.1.0
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.
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.
getMaxLoginAttemptsImpl
protected abstract int getMaxLoginAttemptsImpl()
throws SmartCardException
Returns the maximum number of login attempts allowed, or
Integer.MAX_VALUE if an infinite number of attempts are allowed.
Implementation should not bring up UI.
Returns:
An integer representing the maximum number of login attempts.
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.
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.
getRemainingLoginAttemptsImpl
protected abstract int getRemainingLoginAttemptsImpl()
throws SmartCardException
Returns the remaining number of login attempts allowed before the smartcard will lock,
or Integer.MAX_VALUE if the smart card will not lock.
Implementation should not bring up UI.
Returns:
An integer representing the remaining number of login attempts.
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.
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.
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.
Get a SmartCardID associated with the specific smart card which this session is using.
The implementation should not bring up any UI. The information on the smartcard used to create the SmartCardID
should be available while the user is not logged in to the card.
Returns:
A SmartCardID object associated with the specific smart card which this session is using, or null if the identifier cannot be retrieved..
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.
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.
isLoggedIn
public final boolean isLoggedIn()
Returns true if the session is open and user is logged into the
smartcard, otherwise false.
Returns:
A boolean that determines whether or not the user is logged in.
Since:
JDE 4.1.0
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.
isOpen
public final boolean isOpen()
Returns true if the session is open, otherwise false.
Returns:
A boolean that determines if the session is currently open.
Since:
JDE 4.1.0
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.
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.
Attempts to log the user into the smartcard with the given password.
Implementation should not bring up UI.
Parameters:
password - The password attempt. The password will always be non-null.
Returns:
true if the user was successfully logged, or false otherwise.
Throws:
SmartCardException - Thrown if an error occurs while reading the smart card.
SmartCardLockedException - Thrown if the card becomes locked because the password was incorrect.
Since:
JDE 4.1.0
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.
Prompts the user for their password, and attempts to log the user into
the smartcard. On the last login before the card is locked, a dialog is
displayed indicating to the user that this is their last login attempt.
This method will loop until one of the following occurs:
the user successfully logs into the smartcard.
the user cancels the operation, and a SmartCardCancelException is thrown.
the smartcard becomes locked after the maximum number of login attempts is reached, and a SmartCardLockedException is thrown.
Parameters:
accessReason - The reason for logging into the card. The reason is displayed to the user when prompting for the PIN. May be null.
operation - One of the possible *_OPERATION values.
Throws:
SmartCardException - Thrown if an error occurs while reading the smart card.
SmartCardLockedException - Thrown if the card becomes locked because of incorrect passwords being entered
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.
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.
Copyright 1999-2009 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. Copyright 2002-2003 Nokia Corporation All Rights Reserved. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.