gov.gsc.interfaces

Interface BSI

All Known Implementing Classes:

GSCBSI

public interface BSI

Interface for the BSI 2.1 API.

Method Summary

Modifier and Type	Method and Description
void	gscBsiGcDataCreate(int hCard, java.lang.String AID, short tag, byte[] value) Create a new data item in {Tag, Length, Value} format in the selected container.
void	gscBsiGcDataDelete(int hCard, java.lang.String AID, short tag) Delete the data item associated with the tag value in the specified container.
ContainerProperties	gscBsiGcGetContainerProperties(int hCard, java.lang.String AID) Retrieves the properties of the specified container.
short[]	gscBsiGcReadTagList(int hCard, java.lang.String AID) Return the list of tags in the selected container.
byte[]	gscBsiGcReadValue(int hCard, java.lang.String AID, short tag) Returns the Value associated with the specified Tag.
void	gscBsiGcUpdateValue(int hCard, java.lang.String AID, short tag, byte[] value) Updates the Value associated with the specified Tag.
byte[]	gscBsiGetChallenge(int hCard, java.lang.String AID) Retrieves a randomly generated challenge from the card as the first step of a challenge-response authentication protocol between the client application and the card.
CryptoProperties	gscBsiGetCryptoProperties(int hCard, java.lang.String AID) Retrieves the Access Control Rules associated with the PKI provider module.
byte[]	gscBsiPkiCompute(int hCard, java.lang.String AID, short algoID, byte[] message) Performs a private key computation on the message digest using the private key associated with the specified AID.
byte[]	gscBsiPkiGetCertificate(int hCard, java.lang.String AID) Reads the certificate from the card.
byte[]	gscBsiSkiInternalAuthenticate(int hCard, java.lang.String AID, short algoID, byte[] challenge) Computes a symmetric key cryptogram in response to a challenge.
void	gscBsiUtilAcquireContext(int hCard, java.lang.String AID, java.util.Vector strctAuthenticator) This function shall establish a session with a target container on the smart card by submitting the appropriate Authenticator in the BSIAuthenticator structure.
void	gscBsiUtilBeginTransaction(int hCard, boolean blType) Starts an exclusive transaction with the smart card referenced by hCard.
int	gscBsiUtilConnect(java.lang.String readerName) Establish a logical connection with the card in a specified reader.
void	gscBsiUtilDisconnect(int hCard) Terminate a logical connection to a card.
void	gscBsiUtilEndTransaction(int hCard) Completes a previously started transaction, allowing other applications to resume interactions with the card.
CardProperties	gscBsiUtilGetCardProperties(int hCard) Retrieves ID and capability information for the card.
void	gscBsiUtilGetCardStatus(int hCard) Checks whether a given card handle is associated with a card that is inserted into a powered up reader.
java.lang.String	gscBsiUtilGetExtendedErrorText(int hCard) When a BSI function call throws a BSIException , an application can make a subsequent call to this function to receive additional error information from the card reader driver layer, if available.
java.util.Vector	gscBsiUtilGetReaderList() Retrieves the list of available readers.
java.lang.String	gscBsiUtilGetVersion() Returns the BSI implementation version.
byte[]	gscBsiUtilPassthru(int hCard, byte[] cardCommand) Allows a client application to send a "raw" APDU through the BSI directly to the card and receive the APDU-level response.
void	gscBsiUtilReleaseContext(int hCard, java.lang.String AID) Terminate a session with the target container on the card.
int	gscXsiNotifySynchronizationEnd(int hCard) Stops to notify synchronisation.
int	gscXsiNotifySynchronizationStart(int hCard) Starts to notify synchronisation.
void	gscXsiUtilChangePIN(int hCard, java.lang.String AID, byte[] oldPIN, byte[] newPIN) Change the PIN of the card.
java.lang.String	gscXsiUtilGetCardATR(int hCard) Retrieve the ATR of the card.
int	gscXsiUtilGetCardManagerState(int hCard) Retrieves the Card Manager state.
java.lang.String	gscXsiUtilGetCuid(int hCard) Retrieve the CUID of the card.
int	utilGetLeftPINTries(int hCard, java.lang.String AID) Get the number of left PIN tries of the card.
boolean	utilIsPINVerified(int hCard, java.lang.String AID) Check if the PIN is verified

Method Detail

gscBsiUtilAcquireContext

void gscBsiUtilAcquireContext(int hCard,
                              java.lang.String AID,
                              java.util.Vector strctAuthenticator)
                       throws BSIException

This function shall establish a session with a target container on the smart card by submitting the appropriate Authenticator in the BSIAuthenticator structure. For ACRs requiring external authentication ( XAUTH ), the authValue field of the BSIAuthenticator structure must contain a cryptogram calculated by encrypting a random challenge from gscBsiGetChallenge() . In cases where the card acceptance device authenticates the smart card, this function returns a BSI_TERMINAL_AUTH return code and the cryptogram is ignored. For ACRs that require chained authentication such as BSI_ACR_PIN_AND_XAUTH , the calling application passes in the required authenticators in multiple BSIAuthenticator structures. In this example the calling application passes a PIN and the appropriate External Authentication cryptogram in two BSIAuthenticator structures. The client application must set the accessMethodType field of each BSIAuthenticator structure to match the typeof authenticator contained in the structure. To satisfy an ACR of BSI_ACR_PIN_AND_XAUTH , the application would construct a sequence of two BSIAuthenticators : one containing a PIN and one containing an External Authentication cryptogram. The BSIAuthenticator structure containing the PIN would have an accessMethodType of BSI_AM_PIN , and the BSIAuthenticator structure containing the External Authentication cryptogram would have an accessMethodType of BSI_AM_XAUTH.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

strctAuthenticator: - Vector of BSIAuthenticator objects containing the authenticator(s) specified by the ACR required to access a value in the container. The required list of authenticators is returned by gscBsiGcGetContainerProperties(). The calling application is responsible for constructing this object.

Throws:

BSIException - if an error occurred.

See Also:

BSIAuthenticator

gscBsiUtilConnect

int gscBsiUtilConnect(java.lang.String readerName)
               throws BSIException

Establish a logical connection with the card in a specified reader.

Parameters:

readerName: - Name of the reader that the card is inserted into. If this field is an empty String, the SPS shall attempt to connect to the card in the first available reader, as returned by a call to the BSI’s function gscBsiUtilGetReaderList(). The Name of the reader shall be stored as ASCII encoding Strings.

Returns:

Card connection handle.

Throws:

BSIException - if an error occurred.

gscBsiUtilDisconnect

void gscBsiUtilDisconnect(int hCard)
                   throws BSIException

Terminate a logical connection to a card.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

Throws:

BSIException - if an error occurred.

gscBsiUtilBeginTransaction

void gscBsiUtilBeginTransaction(int hCard,
                                boolean blType)
                         throws BSIException

Starts an exclusive transaction with the smart card referenced by hCard. When the transaction starts, all other applications are precluded from accessing the smart card while the transaction is in progress. Two types of calls can be made with that function: a blocking transaction call and a non-blocking transaction call. A boolean type parameter identify which mode is called. In the non-blocking mode, the call will return immediately if another client has an active transaction lock. The returned error code will be BSI_SC_LOCKED . In the blocking mode, the call will wait indefinitely for any active transaction locks to be released. A transaction must be completed by a call to gscBsiUtilEndTransaction(). For single-threaded BSI implementations, it can be assumed that each application will be associated with a separate process. The same process that starts a transaction must also complete the transaction. For multi-threaded BSI implements, it can be assumed that each application will be associated with a separate thread and/or process. The same thread that starts a transaction must also complete the transaction. If this function is called by a thread that has already called gscBsiUtilBeginTransaction() but has not yet called gscBsiUtilEndTransaction() it will return the error BSI_NOT_TRANSACTED . If the SPS (Service Provider Software) does not support transaction locking, it should return the error code BSI_NO_SPSSERVICE in response to a call to gscBsiUtilBeginTransaction() .

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

blType: - Boolean specifying the type of transaction call ( blType set to true in blocking mode. blType set to false in non blocking mode). In this version it should be true (blocking mode).

Throws:

BSIException - if an error occurred.

gscBsiUtilEndTransaction

void gscBsiUtilEndTransaction(int hCard)
                       throws BSIException

Completes a previously started transaction, allowing other applications to resume interactions with the card. If this function is called by a thread that has not yet called gscBsiUtilBeginTransaction() it will return the error BSI_NOT_TRANSACTED.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

Throws:

BSIException - if an error occurred.

gscBsiUtilGetVersion

java.lang.String gscBsiUtilGetVersion()
                               throws BSIException

Returns the BSI implementation version.

Returns:

A String representing the BSI and SPS’s version formatted as "major,minor,revision,build_number". The value for an SPS conformant with this version of the GSC-IS is "2,1,0". The build number field is vendor/implementation dependent. The version shall be stored as ASCII encoded Strings.

Throws:

BSIException - if an error occurred.

gscBsiUtilGetCardProperties

CardProperties gscBsiUtilGetCardProperties(int hCard)
                                    throws BSIException

Retrieves ID and capability information for the card.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

Returns:

cardProps: A CardProperties object.

Throws:

BSIException - if an error occurred.

See Also:

CardProperties

gscBsiUtilGetCardStatus

void gscBsiUtilGetCardStatus(int hCard)
                      throws BSIException

Checks whether a given card handle is associated with a card that is inserted into a powered up reader.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

Throws:

BSIException - if an error occurred.

gscBsiUtilGetExtendedErrorText

java.lang.String gscBsiUtilGetExtendedErrorText(int hCard)
                                         throws BSIException

When a BSI function call throws a BSIException , an application can make a subsequent call to this function to receive additional error information from the card reader driver layer, if available. Since the GSC-IS architecture accommodates different card reader driver layers, the error text information will be dependent on the card reader driver layer used in a particular implementation. This function must be called immediately after the error has occurred.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

Returns:

errorText: A String of maximum 255 characters including the null terminator, containing an implementation specific error text. If an extended error text string is not available, this function returns an empty string and BSI_NO_TEXT_AVAILABLE . The error text shall be stored as ASCII encoding Strings.

Throws:

BSIException - if an error occurred.

gscBsiUtilGetReaderList

java.util.Vector gscBsiUtilGetReaderList()
                                  throws BSIException

Retrieves the list of available readers.

Returns:

vReaderList: Vector of Strings containing a list of the available readers. The Strings shall be in ASCII format.

Throws:

BSIException - if an error occurred.

gscBsiUtilPassthru

byte[] gscBsiUtilPassthru(int hCard,
                          byte[] cardCommand)
                   throws BSIException

Allows a client application to send a "raw" APDU through the BSI directly to the card and receive the APDU-level response.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

cardCommand: - An array of bytes representing the APDU to be sent to the card. The parameter must be in ASCII hexadecimal format.

Returns:

cardResponse: An array of bytes representing the APDU response from the card. The parameter must be in ASCII hexadecimal format. The response must include the status bytes SW1 and SW2 returned by the card.

Throws:

BSIException - if an error occurred.

gscBsiUtilReleaseContext

void gscBsiUtilReleaseContext(int hCard,
                              java.lang.String AID)
                       throws BSIException

Terminate a session with the target container on the card.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Throws:

BSIException - if an error occurred.

gscXsiUtilGetCardATR

java.lang.String gscXsiUtilGetCardATR(int hCard)
                               throws BSIException

Retrieve the ATR of the card.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

Returns:

Card ATR.

Throws:

BSIException - if an error occurred.

gscXsiUtilGetCuid

java.lang.String gscXsiUtilGetCuid(int hCard)
                            throws BSIException

Retrieve the CUID of the card.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

Returns:

Card CUID.

Throws:

BSIException - if an error occurred.

gscXsiUtilChangePIN

void gscXsiUtilChangePIN(int hCard,
                         java.lang.String AID,
                         byte[] oldPIN,
                         byte[] newPIN)
                  throws BSIException

Change the PIN of the card.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

AID: - target container AID value. The AID shall be stored as an ASCII hexadecimal string.

oldPIN: - value of the current PIN

newPIN: - value of the new PIN

Throws:

BSIException - if an error occurred.

utilIsPINVerified

boolean utilIsPINVerified(int hCard,
                          java.lang.String AID)
                   throws BSIException

Check if the PIN is verified

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

AID: - target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

a boolean value indicating if the PIN is verified

Throws:

BSIException - if an error occurred.

utilGetLeftPINTries

int utilGetLeftPINTries(int hCard,
                        java.lang.String AID)
                 throws BSIException

Get the number of left PIN tries of the card.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

AID: - target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

the number of the left PIN tries

Throws:

BSIException - if an error occurred.

gscBsiGcDataCreate

void gscBsiGcDataCreate(int hCard,
                        java.lang.String AID,
                        short tag,
                        byte[] value)
                 throws BSIException

Create a new data item in {Tag, Length, Value} format in the selected container.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

tag: - Tag of data item to store.

value: - Data value to store.

Throws:

BSIException - if an error occurred.

gscBsiGcDataDelete

void gscBsiGcDataDelete(int hCard,
                        java.lang.String AID,
                        short tag)
                 throws BSIException

Delete the data item associated with the tag value in the specified container.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

tag: - Tag of data item to delete.

Throws:

BSIException - if an error occurred.

gscBsiGcGetContainerProperties

ContainerProperties gscBsiGcGetContainerProperties(int hCard,
                                                   java.lang.String AID)
                                            throws BSIException

Retrieves the properties of the specified container.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

ContainerProperties: A ContainerProperties object.

Throws:

BSIException - if an error occurred.

See Also:

ContainerProperties

gscBsiGcReadTagList

short[] gscBsiGcReadTagList(int hCard,
                            java.lang.String AID)
                     throws BSIException

Return the list of tags in the selected container.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

tagListArray: An array containing the list of tags for the selected container.

Throws:

BSIException - if an error occurred.

gscBsiGcReadValue

byte[] gscBsiGcReadValue(int hCard,
                         java.lang.String AID,
                         short tag)
                  throws BSIException

Returns the Value associated with the specified Tag.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

tag: - Tag value of data item to read.

Returns:

value: Data Value associated with the specified tag.

Throws:

BSIException - if an error occurred.

gscBsiGcUpdateValue

void gscBsiGcUpdateValue(int hCard,
                         java.lang.String AID,
                         short tag,
                         byte[] value)
                  throws BSIException

Updates the Value associated with the specified Tag.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

tag: - Tag value of data item to update.

value: - New Value of the data item.

Throws:

BSIException - if an error occurred.

gscBsiGetChallenge

byte[] gscBsiGetChallenge(int hCard,
                          java.lang.String AID)
                   throws BSIException

Retrieves a randomly generated challenge from the card as the first step of a challenge-response authentication protocol between the client application and the card. The client subsequently encrypts the challenge using a symmetric key and returns the encrypted random challenge to the card through a call to gscBsiUtilAcquireContext() in the authValue instance field of the BSIAuthenticator object.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

challenge: An array of bytes representing a random challenge returned from the card.

Throws:

BSIException - if an error occurred.

gscBsiSkiInternalAuthenticate

byte[] gscBsiSkiInternalAuthenticate(int hCard,
                                     java.lang.String AID,
                                     short algoID,
                                     byte[] challenge)
                              throws BSIException

Computes a symmetric key cryptogram in response to a challenge. In cases where the card reader authenticates the card, this function does not return a cryptogram. In these cases a BSI_TERMINAL_AUTH will be returned if the card reader successfully authenticates the card. BSI_ACCESS_DENIED is returned if the card reader fails to authenticate the card.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

algoID: - Identifies the cryptographic algorithm that the card must use to encrypt the challenge. All conformant implementations shall, at a minimum, support the following algorithms: DES3-ECB (Algorithm Identifier 0x81) and DES3-CBC (Algorithm Identifier0x82). Implementations may optionally support other cryptographic algorithms.

challenge: - Challenge generated by the client application and submitted to the card.

Returns:

cryptogram: The cryptogram computed by the card.

Throws:

BSIException - if an error occurred.

gscBsiPkiCompute

byte[] gscBsiPkiCompute(int hCard,
                        java.lang.String AID,
                        short algoID,
                        byte[] message)
                 throws BSIException

Performs a private key computation on the message digest using the private key associated with the specified AID.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

algoID: - Identifies the cryptographic algorithm that will be used to generate the signature. All conformant implementations shall, at a minimum, support RSA_NO_PAD (Algorithm Identifier 0xA3). Implementations may optionally support other algorithms.

message: - The message digest to be signed.

Returns:

result: An array of bytes containing the signature.

Throws:

BSIException - if an error occurred.

gscBsiPkiGetCertificate

byte[] gscBsiPkiGetCertificate(int hCard,
                               java.lang.String AID)
                        throws BSIException

Reads the certificate from the card.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

certificate: An array of bytes containing the certificate.

Throws:

BSIException - if an error occurred.

gscBsiGetCryptoProperties

CryptoProperties gscBsiGetCryptoProperties(int hCard,
                                           java.lang.String AID)
                                    throws BSIException

Retrieves the Access Control Rules associated with the PKI provider module.

Parameters:

hCard: - Card connection handle from gscBsiUtilConnect().

AID: - Target container AID value. The AID shall be stored as an ASCII hexadecimal string.

Returns:

cryptoProps: A CryptoProperties object.

Throws:

BSIException - if an error occurred.

See Also:

CryptoProperties

gscXsiUtilGetCardManagerState

int gscXsiUtilGetCardManagerState(int hCard)
                           throws BSIException

Retrieves the Card Manager state.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

Returns:

the Card Manager state

Throws:

BSIException - if an error occurred.

gscXsiNotifySynchronizationStart

int gscXsiNotifySynchronizationStart(int hCard)
                              throws BSIException

Starts to notify synchronisation.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

Returns:

the notify synchronisation state

Throws:

BSIException - if an error occurred.

gscXsiNotifySynchronizationEnd

int gscXsiNotifySynchronizationEnd(int hCard)
                            throws BSIException

Stops to notify synchronisation.

Parameters:

hCard: - card connection handle from gscBsiUtilConnect().

Returns:

the notify synchronisation state

Throws:

BSIException - if an error occurred.