be.fedict.commons.eid.client

Class BeIDCard

java.lang.Object

be.fedict.commons.eid.client.BeIDCard

public class BeIDCard
extends Object

One BeIDCard instance represents one Belgian Electronic Identity Card, physically present in a connected javax.smartcardio.CardTerminal. It exposes the publicly accessible features of the BELPIC applet on the card's chip:

• Reading Certificates and Certificate Chains
• Signing of digests non-repudiation and authentication purposes
• Verification and Alteration of the PIN code
• Reading random bytes from the on-board random generator
• Creating text message transaction signatures on specialized readers
• PIN unblocking using PUK codes

BeIDCard instances rely on an instance of BeIDCardUI to support user interaction, such as obtaining PIN and PUK codes for authentication, signing, verifying, changing PIN codes, and for notifying the user of the progress of such operations on a Secure Pinpad Device. A default implementation is available as DefaultBeIDCardUI, and unless replaced by an explicit call to setUI() will automatically be used (when present in the class path).

BeIDCard instances automatically detect CCID features in the underlying CardTerminal, and will choose the most secure path where several are available, for example, when needing to acquire PIN codes from the user, and the card is in a CCID-compliant Secure Pinpad Reader the PIN entry features of the reader will be used instead of the corresponding "obtain.." feature from the active BeIDCardUI. In that case, the corresponding "advise.." method of the active BeIDCardUI will be called instead, to advise the user to attend to the SPR.

To receive notifications of the progress of lengthy operations such as reading 'files' (certificates, photo,..) or signing (which may be lengthy because of user PIN interaction), register an instance of BeIDCardListener using addCardListener(). This is useful, for example, for providing progress indication to the user.

For detailed progress and error/debug logging, provide an instance of be.fedict.commons.eid.spi.Logger to BeIDCard's constructor (the default VoidLogger discards all logging and debug messages). You are advised to provide some form of logging facility, for all but the most trivial applications.

Author:

Frank Cornelis, Frank Marien

Constructor Summary

Constructors

Constructor and Description
BeIDCard(javax.smartcardio.Card card) Instantiate a BeIDCard from an already connected javax.smartcardio.Card no logging information will be available.
BeIDCard(javax.smartcardio.Card card, Logger logger) Instantiate a BeIDCard from an already connected javax.smartcardio.Card, with a Logger implementation to receive logging output.
BeIDCard(javax.smartcardio.CardTerminal cardTerminal) Instantiate a BeIDCard from a javax.smartcardio.CardTerminal, with no logging information will be available.
BeIDCard(javax.smartcardio.CardTerminal cardTerminal, Logger logger) Instantiate a BeIDCard from a javax.smartcardio.CardTerminal, with a Logger implementation to receive logging output.

Method Summary

Modifier and Type	Method and Description
BeIDCard	addCardListener(BeIDCardListener beIDCardListener) Register a BeIDCardListener to receive updates on any consequent file reading/signature operations executed by this BeIDCard.
BeIDCard	beginExclusive() Begin an exclusive transaction with the card.
boolean	cardTerminalHasCCIDFeature(CCID.FEATURE feature) test for CCID Features in the card reader this BeIDCard is inserted into
void	changePin(boolean requireSecureReader) Change PIN code.
BeIDCard	close() close this BeIDCard, when you are done with it, to release any underlying resources.
BeIDCard	endExclusive() Release an exclusive transaction with the card, started by beginExclusive().
javax.smartcardio.ATR	getATR() getATR returns the ATR of the eID Card.
X509Certificate	getAuthenticationCertificate() Returns the X509 authentication certificate.
List<X509Certificate>	getAuthenticationCertificateChain() Returns the X509 authentication certificate chain.
ECPublicKey	getBasicPublicKey() Gives back the basic public key file.
X509Certificate	getCACertificate() Returns the citizen CA certificate.
List<X509Certificate>	getCACertificateChain() Returns the Citizen CA X509 certificate chain.
byte[]	getCardData() Gives back the card data as byte array.
javax.smartcardio.CardTerminal	getCardTerminal() Return the CardTerminal that held this BeIdCard when it was detected Will return null if the physical Card that we represent was removed.
X509Certificate	getCertificate(FileType fileType) Reads a certain certificate from the card.
List<X509Certificate>	getCertificateChain(FileType fileType) Returns the entire certificate chain for a given file type.
byte[]	getChallenge(int size) Returns random data generated by the eID card itself.
Locale	getLocale()
List<byte[]>	getRawAuthenticationCertificateChain()
List<byte[]>	getRawCertificateChain(FileType fileType)
List<byte[]>	getRawRRNCertificateChain()
List<byte[]>	getRawSigningCertificateChain()
X509Certificate	getRootCACertificate() Returns the Root CA certificate.
X509Certificate	getRRNCertificate() Returns the national registration certificate.
List<X509Certificate>	getRRNCertificateChain() Returns the national registry X509 certificate chain.
X509Certificate	getSigningCertificate() Returns the X509 non-repudiation certificate.
List<X509Certificate>	getSigningCertificateChain() Returns the X509 non-repudiation certificate chain.
byte[]	internalAuthenticate(byte[] challenge) Performs an internal authentication, i.e., authentication of the eID card itself.
boolean	isEC() Returns true if this eID card supports elliptic curve crypto.
BeIDCard	logoff() Discard the citizen's PIN code from the PIN cache.
byte[]	readBinary(FileType fileType, int estimatedMaxSize) Read bytes from a previously selected "File" on the card. should be preceded by a call to selectFile so the card knows what you want to read.
byte[]	readFile(FileType fileType) Reads a file from the card.
BeIDCard	removeCardListener(BeIDCardListener beIDCardListener) Unregister a BeIDCardListener to no longer receive updates on any consequent file reading/signature operations executed by this BeIDCard.
BeIDCard	selectApplet() Select the BELPIC applet on the chip.
BeIDCard	selectFile(byte[] fileId) Selects a file to read on the card
void	setCardTerminal(javax.smartcardio.CardTerminal cardTerminal)
BeIDCard	setLocale(Locale newLocale) set the Locale to use for subsequent UI and CCID operations. this will modify the Locale of any explicitly set UI, as well.
BeIDCard	setUI(BeIDCardUI userInterface) Explicitly set the User Interface to be used for consequent operations.
byte[]	sign(byte[] digestValue, BeIDDigest digestAlgo, FileType fileType, boolean requireSecureReader) Sign a given digest value.
byte[]	sign(byte[] digestValue, BeIDDigest digestAlgo, FileType fileType, boolean requireSecureReader, String applicationName) Sign a given digest value.
byte[]	signAuthn(byte[] toBeSigned, boolean requireSecureReader) Create an authentication signature.
byte[]	signAuthn(byte[] toBeSigned, boolean requireSecureReader, String applicationName) Create an authentication signature.
byte[]	signTransactionMessage(String transactionMessage, boolean requireSecureReader) Create a text message transaction signature.
byte[]	signTransactionMessage(String transactionMessage, boolean requireSecureReader, String applicationName) Create a text message transaction signature.
protected byte[]	transmitCCIDControl(boolean usePPDU, CCID.FEATURE feature)
protected byte[]	transmitCCIDControl(boolean usePPDU, CCID.FEATURE feature, byte[] command)
protected javax.smartcardio.ResponseAPDU	transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu, byte[] data)
protected javax.smartcardio.ResponseAPDU	transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu, byte[] data, int dataOffset, int dataLength, int ne)
protected javax.smartcardio.ResponseAPDU	transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu, int le)
protected javax.smartcardio.ResponseAPDU	transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu, int p2, byte[] data)
protected javax.smartcardio.ResponseAPDU	transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu, int p1, int p2, int le)
protected byte[]	transmitControlCommand(int controlCode, byte[] command)
protected byte[]	transmitPPDUCommand(int controlCode, byte[] command)
void	unblockPin(boolean requireSecureReader) Unblocking PIN using PUKs.
void	verifyPin() Verifying PIN Code (without other actions, for testing PIN), using the most secure method available.
void	verifyPin(String applicationName) Verifying PIN Code (without other actions, for testing PIN), using the most secure method available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BeIDCard

public BeIDCard(javax.smartcardio.Card card,
                Logger logger)

Instantiate a BeIDCard from an already connected javax.smartcardio.Card, with a Logger implementation to receive logging output.

Parameters:

card - a javax.smartcardio.Card that you have previously determined to be a BeID Card

logger - an instance of be.fedict.commons.eid.spi.Logger

Throws:

IllegalArgumentException - when passed a null logger. to disable logging, call BeIDCard(Card) instead.

RuntimeException - when no CertificateFactory capable of producing X509 Certificates is available.

BeIDCard

public BeIDCard(javax.smartcardio.Card card)

Instantiate a BeIDCard from an already connected javax.smartcardio.Card no logging information will be available.

Parameters:

card - a javax.smartcardio.Card that you have previously determined to be a BeID Card

Throws:

RuntimeException - when no CertificateFactory capable of producing X509 Certificates is available.

BeIDCard

public BeIDCard(javax.smartcardio.CardTerminal cardTerminal,
                Logger logger)
         throws javax.smartcardio.CardException

Instantiate a BeIDCard from a javax.smartcardio.CardTerminal, with a Logger implementation to receive logging output.

Parameters:

cardTerminal - a javax.smartcardio.CardTerminal that you have previously determined to contain a BeID Card

logger - an instance of be.fedict.commons.eid.spi.Logger

Throws:

IllegalArgumentException - when passed a null logger. to disable logging, call public BeIDCard(CardTerminal) instead.

RuntimeException - when no CertificateFactory capable of producing X509 Certificates is available.

javax.smartcardio.CardException - in case of a smart card I/O error.

BeIDCard

public BeIDCard(javax.smartcardio.CardTerminal cardTerminal)
         throws javax.smartcardio.CardException

Instantiate a BeIDCard from a javax.smartcardio.CardTerminal, with no logging information will be available.

Parameters:

cardTerminal - a javax.smartcardio.CardTerminal that you have previously determined to contain a BeID Card

Throws:

RuntimeException - when no CertificateFactory capable of producing X509 Certificates is available.

javax.smartcardio.CardException - in case of a smart card I/O error.

Method Detail

close

public BeIDCard close()

close this BeIDCard, when you are done with it, to release any underlying resources. All subsequent calls will fail.

Returns:

this BeIDCard instance, to allow method chaining

setUI

public final BeIDCard setUI(BeIDCardUI userInterface)

Explicitly set the User Interface to be used for consequent operations. All user interaction is handled through this, and possible SPR features of CCID-capable CardReaders. This will also modify the Locale setting of this beIDCard instance to match the UI's Locale, so the language in any SPR messages displayed will be consistent with the UI's language.

Parameters:

userInterface - an instance of BeIDCardUI

Returns:

this BeIDCard instance, to allow method chaining

addCardListener

public final BeIDCard addCardListener(BeIDCardListener beIDCardListener)

Register a BeIDCardListener to receive updates on any consequent file reading/signature operations executed by this BeIDCard.

Parameters:

beIDCardListener - a beIDCardListener instance

Returns:

this BeIDCard instance, to allow method chaining

removeCardListener

public final BeIDCard removeCardListener(BeIDCardListener beIDCardListener)

Unregister a BeIDCardListener to no longer receive updates on any consequent file reading/signature operations executed by this BeIDCard.

Parameters:

beIDCardListener - a beIDCardListener instance

Returns:

this BeIDCard instance, to allow method chaining

getCertificate

public X509Certificate getCertificate(FileType fileType)
                               throws CertificateException,
                                      javax.smartcardio.CardException,
                                      IOException,
                                      InterruptedException

Reads a certain certificate from the card. Which certificate to read is determined by the FileType param. Applicable FileTypes are AuthentificationCertificate, NonRepudiationCertificate, CACertificate, RootCertificate and RRNCertificate.

Parameters:

fileType -

Returns:

the certificate requested

Throws:

CertificateException

javax.smartcardio.CardException

IOException

InterruptedException

getAuthenticationCertificate

public X509Certificate getAuthenticationCertificate()
                                             throws javax.smartcardio.CardException,
                                                    IOException,
                                                    CertificateException,
                                                    InterruptedException

Returns the X509 authentication certificate. This is a convenience method for getCertificate(FileType.AuthentificationCertificate)

Returns:

the X509 Authentication Certificate from the card.

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getSigningCertificate

public X509Certificate getSigningCertificate()
                                      throws javax.smartcardio.CardException,
                                             IOException,
                                             CertificateException,
                                             InterruptedException

Returns the X509 non-repudiation certificate. This is a convencience method for getCertificate(FileType.NonRepudiationCertificate)

Returns:

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getCACertificate

public X509Certificate getCACertificate()
                                 throws javax.smartcardio.CardException,
                                        IOException,
                                        CertificateException,
                                        InterruptedException

Returns the citizen CA certificate. This is a convenience method for getCertificate(FileType.CACertificate)

Returns:

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getRootCACertificate

public X509Certificate getRootCACertificate()
                                     throws CertificateException,
                                            javax.smartcardio.CardException,
                                            IOException,
                                            InterruptedException

Returns the Root CA certificate.

Returns:

the Root CA X509 certificate.

Throws:

CertificateException

javax.smartcardio.CardException

IOException

InterruptedException

getRRNCertificate

public X509Certificate getRRNCertificate()
                                  throws javax.smartcardio.CardException,
                                         IOException,
                                         CertificateException,
                                         InterruptedException

Returns the national registration certificate. This is a convencience method for getCertificate(FileType.RRNCertificate)

Returns:

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getCertificateChain

public List<X509Certificate> getCertificateChain(FileType fileType)
                                          throws CertificateException,
                                                 javax.smartcardio.CardException,
                                                 IOException,
                                                 InterruptedException

Returns the entire certificate chain for a given file type. Of course, only file types corresponding with a certificate are accepted. Which certificate's chain to return is determined by the FileType param. Applicable FileTypes are AuthentificationCertificate, NonRepudiationCertificate, CACertificate, and RRNCertificate.

Parameters:

fileType - which certificate's chain to return

Returns:

the certificate's chain up to and including the Belgian Root Cert

Throws:

CertificateException

javax.smartcardio.CardException

IOException

InterruptedException

getRawCertificateChain

public List<byte[]> getRawCertificateChain(FileType fileType)
                                    throws javax.smartcardio.CardException,
                                           IOException,
                                           InterruptedException

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

getAuthenticationCertificateChain

public List<X509Certificate> getAuthenticationCertificateChain()
                                                        throws javax.smartcardio.CardException,
                                                               IOException,
                                                               CertificateException,
                                                               InterruptedException

Returns the X509 authentication certificate chain. (Authentication -> Citizen CA -> Root) This is a convenience method for getCertificateChain(FileType.AuthentificationCertificate)

Returns:

the authentication certificate chain

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getRawAuthenticationCertificateChain

public List<byte[]> getRawAuthenticationCertificateChain()
                                                  throws javax.smartcardio.CardException,
                                                         IOException,
                                                         InterruptedException

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

getSigningCertificateChain

public List<X509Certificate> getSigningCertificateChain()
                                                 throws javax.smartcardio.CardException,
                                                        IOException,
                                                        CertificateException,
                                                        InterruptedException

Returns the X509 non-repudiation certificate chain. (Non-Repudiation -> Citizen CA -> Root) This is a convenience method for getCertificateChain(FileType.NonRepudiationCertificate)

Returns:

the non-repudiation certificate chain

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getRawSigningCertificateChain

public List<byte[]> getRawSigningCertificateChain()
                                           throws javax.smartcardio.CardException,
                                                  IOException,
                                                  InterruptedException

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

getCACertificateChain

public List<X509Certificate> getCACertificateChain()
                                            throws javax.smartcardio.CardException,
                                                   IOException,
                                                   CertificateException,
                                                   InterruptedException

Returns the Citizen CA X509 certificate chain. (Citizen CA -> Root) This is a convenience method for getCertificateChain(FileType.CACertificate)

Returns:

the citizen ca certificate chain

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getRRNCertificateChain

public List<X509Certificate> getRRNCertificateChain()
                                             throws javax.smartcardio.CardException,
                                                    IOException,
                                                    CertificateException,
                                                    InterruptedException

Returns the national registry X509 certificate chain. (National Registry -> Root) This is a convenience method for getCertificateChain(FileType.RRNCertificate)

Returns:

the national registry certificate chain

Throws:

javax.smartcardio.CardException

IOException

CertificateException

InterruptedException

getRawRRNCertificateChain

public List<byte[]> getRawRRNCertificateChain()
                                       throws javax.smartcardio.CardException,
                                              IOException,
                                              InterruptedException

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

getBasicPublicKey

public ECPublicKey getBasicPublicKey()
                              throws javax.smartcardio.CardException,
                                     IOException,
                                     InterruptedException,
                                     InvalidKeySpecException

Gives back the basic public key file. This file is available on belpic applet version 1.8 eID cards.

Returns:

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

InvalidKeySpecException

sign

public byte[] sign(byte[] digestValue,
                   BeIDDigest digestAlgo,
                   FileType fileType,
                   boolean requireSecureReader)
            throws javax.smartcardio.CardException,
                   IOException,
                   InterruptedException,
                   UserCancelledException

Sign a given digest value.

Parameters:

digestValue - the digest value to be signed.

digestAlgo - the algorithm used to calculate the given digest value.

fileType - the certificate's file type.

requireSecureReader - true if a secure pinpad reader is required.

Returns:

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

sign

public byte[] sign(byte[] digestValue,
                   BeIDDigest digestAlgo,
                   FileType fileType,
                   boolean requireSecureReader,
                   String applicationName)
            throws javax.smartcardio.CardException,
                   IOException,
                   InterruptedException,
                   UserCancelledException

Sign a given digest value.

Parameters:

digestValue - the digest value to be signed.

digestAlgo - the algorithm used to calculate the given digest value.

fileType - the certificate's file type.

requireSecureReader - true if a secure pinpad reader is required.

applicationName - the optional application name.

Returns:

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

signAuthn

public byte[] signAuthn(byte[] toBeSigned,
                        boolean requireSecureReader)
                 throws NoSuchAlgorithmException,
                        javax.smartcardio.CardException,
                        IOException,
                        InterruptedException,
                        UserCancelledException

Create an authentication signature.

Parameters:

toBeSigned - the data to be signed

requireSecureReader - whether to require a secure pinpad reader to obtain the citizen's PIN if false, the current BeIDCardUI will be used in the absence of a secure pinpad reader. If true, an exception will be thrown unless an SPR is available

Returns:

a SHA-1 digest of the input data signed by the citizen's authentication key

Throws:

NoSuchAlgorithmException

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

signAuthn

public byte[] signAuthn(byte[] toBeSigned,
                        boolean requireSecureReader,
                        String applicationName)
                 throws NoSuchAlgorithmException,
                        javax.smartcardio.CardException,
                        IOException,
                        InterruptedException,
                        UserCancelledException

Create an authentication signature.

Parameters:

toBeSigned - the data to be signed

requireSecureReader - whether to require a secure pinpad reader to obtain the citizen's PIN if false, the current BeIDCardUI will be used in the absence of a secure pinpad reader. If true, an exception will be thrown unless an SPR is available

applicationName - the optional application name.

Returns:

a SHA-1 digest of the input data signed by the citizen's authentication key

Throws:

NoSuchAlgorithmException

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

internalAuthenticate

public byte[] internalAuthenticate(byte[] challenge)
                            throws javax.smartcardio.CardException

Performs an internal authentication, i.e., authentication of the eID card itself.

Parameters:

challenge -

Returns:

Throws:

javax.smartcardio.CardException

verifyPin

public void verifyPin()
               throws IOException,
                      javax.smartcardio.CardException,
                      InterruptedException,
                      UserCancelledException

Verifying PIN Code (without other actions, for testing PIN), using the most secure method available. Note that this still has the side effect of loading a successfully tests PIN into the PIN cache, so that unless the card is removed, a subsequent authentication attempt will not request the PIN, but proceed with the PIN given here.

Throws:

IOException

javax.smartcardio.CardException

InterruptedException

UserCancelledException

verifyPin

public void verifyPin(String applicationName)
               throws IOException,
                      javax.smartcardio.CardException,
                      InterruptedException,
                      UserCancelledException

Verifying PIN Code (without other actions, for testing PIN), using the most secure method available. Note that this still has the side effect of loading a successfully tests PIN into the PIN cache, so that unless the card is removed, a subsequent authentication attempt will not request the PIN, but proceed with the PIN given here.

Parameters:

applicationName - the optional application name.

Throws:

IOException

javax.smartcardio.CardException

InterruptedException

UserCancelledException

changePin

public void changePin(boolean requireSecureReader)
               throws Exception

Change PIN code. This method will attempt to change PIN using the most secure method available. if requiresSecureReader is true, this will throw a SecurityException if no SPR is available, otherwise, this will default to changing the PIN via the UI

Parameters:

requireSecureReader -

Throws:

Exception

getChallenge

public byte[] getChallenge(int size)
                    throws javax.smartcardio.CardException

Returns random data generated by the eID card itself.

Parameters:

size - the size of the requested random data.

Returns:

size bytes of random data

Throws:

javax.smartcardio.CardException

signTransactionMessage

public byte[] signTransactionMessage(String transactionMessage,
                                     boolean requireSecureReader)
                              throws javax.smartcardio.CardException,
                                     IOException,
                                     InterruptedException,
                                     UserCancelledException

Create a text message transaction signature. The FedICT eID aware secure pinpad readers can visualize such type of text message transactions on their hardware display.

Parameters:

transactionMessage - the transaction message to be signed.

requireSecureReader -

Returns:

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

signTransactionMessage

public byte[] signTransactionMessage(String transactionMessage,
                                     boolean requireSecureReader,
                                     String applicationName)
                              throws javax.smartcardio.CardException,
                                     IOException,
                                     InterruptedException,
                                     UserCancelledException

Create a text message transaction signature. The FedICT eID aware secure pinpad readers can visualize such type of text message transactions on their hardware display.

Parameters:

transactionMessage - the transaction message to be signed.

requireSecureReader -

applicationName - the optional application name.

Returns:

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

UserCancelledException

logoff

public BeIDCard logoff()
                throws Exception

Discard the citizen's PIN code from the PIN cache. Any subsequent Authentication signatures will require PIN entry. (non-repudation signatures are automatically protected)

Returns:

this BeIDCard instance, to allow method chaining

Throws:

Exception

unblockPin

public void unblockPin(boolean requireSecureReader)
                throws Exception

Unblocking PIN using PUKs. This will choose the most secure method available to unblock a blocked PIN. If requireSecureReader is true, will throw SecurityException if an SPR is not available

Parameters:

requireSecureReader -

Throws:

Exception

getATR

public javax.smartcardio.ATR getATR()

getATR returns the ATR of the eID Card. If this BeIDCard instance was constructed using the CardReader constructor, this is the only way to get to the ATR.

Returns:

getLocale

public Locale getLocale()

Returns:

the current Locale used in CCID SPR operations and UI

setLocale

public BeIDCard setLocale(Locale newLocale)

set the Locale to use for subsequent UI and CCID operations. this will modify the Locale of any explicitly set UI, as well. BeIDCard instances, while using the global Locale settings made in BeIDCards and/or BeIDCardManager by default, may have their own individual Locale settings that may override those global settings.

Parameters:

newLocale -

Returns:

this BeIDCard instance, to allow method chaining

selectApplet

public BeIDCard selectApplet()
                      throws javax.smartcardio.CardException

Select the BELPIC applet on the chip. Since the BELPIC applet is supposed to be all alone on the chip, shouldn't be necessary.

Returns:

this BeIDCard instance, to allow method chaining

Throws:

javax.smartcardio.CardException

beginExclusive

public BeIDCard beginExclusive()
                        throws javax.smartcardio.CardException

Begin an exclusive transaction with the card. Once this returns, only the calling thread will be able to access the card, until it calls endExclusive(). Other threads will receive a CardException. Use this when you need to make several calls to the card that depend on each other. for example, SELECT FILE and READ BINARY, or SELECT ALGORITHM and COMPUTE SIGNATURE, to avoid other threads/processes from interleaving commands that would break your transactional logic. Called automatically by the higher-level methods in this class. If you end up calling this directly, this is either something wrong with your code, or with this class. Please let us know. You should really only have to be calling this when using some of the other low-level methods (transmitCommand, etc..) *never* in combination with the high-level methods.

Returns:

this BeIDCard Instance, to allow method chaining.

Throws:

javax.smartcardio.CardException

endExclusive

public BeIDCard endExclusive()
                      throws javax.smartcardio.CardException

Release an exclusive transaction with the card, started by beginExclusive().

Returns:

this BeIDCard Instance, to allow method chaining.

Throws:

javax.smartcardio.CardException

readBinary

public byte[] readBinary(FileType fileType,
                         int estimatedMaxSize)
                  throws javax.smartcardio.CardException,
                         IOException,
                         InterruptedException

Read bytes from a previously selected "File" on the card. should be preceded by a call to selectFile so the card knows what you want to read. Consider using one of the higher-level methods, or readFile().

Parameters:

fileType - the file to read (to allow for notification)

estimatedMaxSize - the estimated total size of the file to read (to allow for notification)

Returns:

the data from the file

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

selectFile

public BeIDCard selectFile(byte[] fileId)
                    throws javax.smartcardio.CardException,
                           FileNotFoundException

Selects a file to read on the card

Parameters:

fileId - the file to read

Returns:

this BeIDCard Instance, to allow method chaining.

Throws:

javax.smartcardio.CardException

FileNotFoundException

readFile

public byte[] readFile(FileType fileType)
                throws javax.smartcardio.CardException,
                       IOException,
                       InterruptedException

Reads a file from the card.

Parameters:

fileType - the file to read

Returns:

the data from the file

Throws:

javax.smartcardio.CardException

IOException

InterruptedException

cardTerminalHasCCIDFeature

public boolean cardTerminalHasCCIDFeature(CCID.FEATURE feature)

test for CCID Features in the card reader this BeIDCard is inserted into

Parameters:

feature - the feature to test for (CCID.FEATURE)

Returns:

true if the given feature is available, false if not

getCardData

public byte[] getCardData()
                   throws javax.smartcardio.CardException,
                          FileNotFoundException

Gives back the card data as byte array. For Belpic applet version 1.8 eID cards, this will return the extended version.

Returns:

Throws:

javax.smartcardio.CardException

FileNotFoundException

isEC

public boolean isEC()

Returns true if this eID card supports elliptic curve crypto.

Returns:

transmitCCIDControl

protected byte[] transmitCCIDControl(boolean usePPDU,
                                     CCID.FEATURE feature)
                              throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCCIDControl

protected byte[] transmitCCIDControl(boolean usePPDU,
                                     CCID.FEATURE feature,
                                     byte[] command)
                              throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitControlCommand

protected byte[] transmitControlCommand(int controlCode,
                                        byte[] command)
                                 throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitPPDUCommand

protected byte[] transmitPPDUCommand(int controlCode,
                                     byte[] command)
                              throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCommand

protected javax.smartcardio.ResponseAPDU transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu,
                                                         int le)
                                                  throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCommand

protected javax.smartcardio.ResponseAPDU transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu,
                                                         int p2,
                                                         byte[] data)
                                                  throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCommand

protected javax.smartcardio.ResponseAPDU transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu,
                                                         int p1,
                                                         int p2,
                                                         int le)
                                                  throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCommand

protected javax.smartcardio.ResponseAPDU transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu,
                                                         byte[] data)
                                                  throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

transmitCommand

protected javax.smartcardio.ResponseAPDU transmitCommand(be.fedict.commons.eid.client.BeIDCard.BeIDCommandAPDU apdu,
                                                         byte[] data,
                                                         int dataOffset,
                                                         int dataLength,
                                                         int ne)
                                                  throws javax.smartcardio.CardException

Throws:

javax.smartcardio.CardException

getCardTerminal

public javax.smartcardio.CardTerminal getCardTerminal()

Return the CardTerminal that held this BeIdCard when it was detected Will return null if the physical Card that we represent was removed.

Returns:

the cardTerminal this BeIDCard was in when detected, or null

setCardTerminal

public void setCardTerminal(javax.smartcardio.CardTerminal cardTerminal)

Parameters:

cardTerminal -