Skip to content
This repository has been archived by the owner on Feb 12, 2024. It is now read-only.

Commit

Permalink
docs: improve javadoc for CalypsoCard, selection and transaction mana…
Browse files Browse the repository at this point in the history
…gers
  • Loading branch information
andrei-cristea committed Mar 8, 2023
1 parent 585a469 commit f28a6e9
Show file tree
Hide file tree
Showing 3 changed files with 116 additions and 20 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.calypsonet.terminal.calypso.GetDataTag;
import org.calypsonet.terminal.calypso.SelectFileControl;
import org.calypsonet.terminal.calypso.WriteAccessLevel;
import org.calypsonet.terminal.calypso.transaction.CardTransactionManager;
import org.calypsonet.terminal.calypso.transaction.SvAction;
import org.calypsonet.terminal.calypso.transaction.SvOperation;
import org.calypsonet.terminal.reader.selection.spi.SmartCard;

/**
Expand Down Expand Up @@ -174,6 +180,8 @@ public interface CalypsoCard extends SmartCard {
* <p>The returned array contains the software issuer ID and the discretionary data.
*
* @return An empty array if the traceability information is not available.
* @see CalypsoCardSelection#prepareGetData(GetDataTag)
* @see CardTransactionManager#prepareGetData(GetDataTag)
* @since 1.1.0
*/
byte[] getTraceabilityInformation();
Expand All @@ -182,6 +190,10 @@ public interface CalypsoCard extends SmartCard {
* Returns the metadata of the current DF.
*
* @return Null if is not set.
* @see CalypsoCardSelection#prepareSelectFile(short)
* @see CalypsoCardSelection#prepareSelectFile(SelectFileControl)
* @see CardTransactionManager#prepareSelectFile(short)
* @see CardTransactionManager#prepareSelectFile(SelectFileControl)
* @since 1.0.0
*/
DirectoryHeader getDirectoryHeader();
Expand All @@ -192,6 +204,9 @@ public interface CalypsoCard extends SmartCard {
* <p>Note that if a secure session is actually running, then the object contains all session
* modifications, which can be canceled if the secure session fails.
*
* <p>The file structure of the card image is updated as a result of file read and write
* operations.
*
* @param sfi The SFI to search.
* @return Null if the requested EF is not found or if the SFI is equal to 0.
* @since 1.0.0
Expand All @@ -204,6 +219,9 @@ public interface CalypsoCard extends SmartCard {
* <p>Note that if a secure session is actually running, then the object contains all session
* modifications, which can be canceled if the secure session fails.
*
* <p>The file structure of the card image is updated as a result of file read and write
* operations.
*
* @param lid The LID to search.
* @return Null if the requested EF is not found.
* @since 1.0.0
Expand All @@ -230,6 +248,9 @@ public interface CalypsoCard extends SmartCard {
* <p>Note that if a secure session is actually running, then the set contains all session
* modifications, which can be canceled if the secure session fails.
*
* <p>The file structure of the card image is updated as a result of file read and write
* operations.
*
* @return A not null reference (it may be empty if no one EF is set).
* @since 1.1.0
*/
Expand All @@ -240,6 +261,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return True if the card has been ratified.
* @throws IllegalStateException If no session has been opened.
* @see CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
* @see CardTransactionManager#prepareOpenSecureSession(WriteAccessLevel)
* @since 1.0.0
*/
boolean isDfRatified();
Expand All @@ -254,6 +277,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return A positive value.
* @throws IllegalStateException If no session has been opened.
* @see CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
* @see CardTransactionManager#prepareOpenSecureSession(WriteAccessLevel)
* @since 1.2.0
*/
int getTransactionCounter();
Expand Down Expand Up @@ -307,6 +332,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return True if the PIN status is blocked
* @throws IllegalStateException If the PIN has not been checked.
* @see CardTransactionManager#prepareCheckPinStatus()
* @see CardTransactionManager#prepareVerifyPin(byte[])
* @since 1.0.0
*/
boolean isPinBlocked();
Expand All @@ -316,6 +343,8 @@ public interface CalypsoCard extends SmartCard {
*
* @return The number of remaining attempts.
* @throws IllegalStateException If the PIN has not been checked.
* @see CardTransactionManager#prepareCheckPinStatus()
* @see CardTransactionManager#prepareVerifyPin(byte[])
* @since 1.0.0
*/
int getPinAttemptRemaining();
Expand All @@ -335,6 +364,11 @@ public interface CalypsoCard extends SmartCard {
*
* @return An int
* @throws IllegalStateException If no SV Get command has been executed.
* @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
* @see CardTransactionManager#prepareSvDebit(int)
* @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
* @see CardTransactionManager#prepareSvReload(int)
* @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
int getSvBalance();
Expand All @@ -344,6 +378,11 @@ public interface CalypsoCard extends SmartCard {
*
* @return An int
* @throws IllegalStateException If no SV Get command has been executed.
* @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
* @see CardTransactionManager#prepareSvDebit(int)
* @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
* @see CardTransactionManager#prepareSvReload(int)
* @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
int getSvLastTNum();
Expand All @@ -352,6 +391,11 @@ public interface CalypsoCard extends SmartCard {
* Gets a reference to the last {@link SvLoadLogRecord}
*
* @return A last SV load log record object or null if not available.
* @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
* @see CardTransactionManager#prepareSvDebit(int)
* @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
* @see CardTransactionManager#prepareSvReload(int)
* @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
SvLoadLogRecord getSvLoadLogRecord();
Expand All @@ -360,6 +404,11 @@ public interface CalypsoCard extends SmartCard {
* Gets a reference to the last {@link SvDebitLogRecord}
*
* @return A last SV debit log record object or null if not available.
* @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
* @see CardTransactionManager#prepareSvDebit(int)
* @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
* @see CardTransactionManager#prepareSvReload(int)
* @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
SvDebitLogRecord getSvDebitLogLastRecord();
Expand All @@ -368,6 +417,11 @@ public interface CalypsoCard extends SmartCard {
* Gets list of references to the {@link SvDebitLogRecord} read from the card.
*
* @return An empty list if no log records are available.
* @see CardTransactionManager#prepareSvGet(SvOperation, SvAction)
* @see CardTransactionManager#prepareSvDebit(int)
* @see CardTransactionManager#prepareSvDebit(int, byte[], byte[])
* @see CardTransactionManager#prepareSvReload(int)
* @see CardTransactionManager#prepareSvReload(int, byte[], byte[], byte[])
* @since 1.0.0
*/
List<SvDebitLogRecord> getSvDebitLogAllRecords();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ public interface CalypsoCardSelection extends CardSelection {
* Adds a command APDU to read a single record from the indicated EF.
*
* <p>Once this command is processed, the result is available in {@link CalypsoCard} if the
* requested file and record exist in the file structure of the card (best effort behavior).
* requested file and record exist in the file structure of the card (best-effort mode).
*
* <p>Caution: the resulting APDU command must be compliant with PRIME revision 3 cards.
* Therefore, the command may be rejected by some earlier revision cards.
Expand Down Expand Up @@ -289,8 +289,43 @@ public interface CalypsoCardSelection extends CardSelection {
* feature, this optimizes future exchanges with the card in the case of secure sessions intended
* to be executed in a single step.
*
* <p>Caution: the resulting APDU command is compliant with PRIME revision 3 cards supporting the
* extended mode. Therefore, the command may be rejected by some earlier revision cards.
* <p>The objective of the pre-opening is to allow the grouping of all the commands of a secure
* session. This functionality is only relevant in the case of a distributed system where the
* ticketing processing is done remotely in order to allow a complete secure session to be carried
* out in a single exchange between the server and the terminal.
*
* <p>This mechanism is based on the anticipation of the APDU responses of the card.
*
* <p>In order to achieve the objective of a single exchange, it is essential to read locally
* beforehand (out of session) all the data that will have to be read in session. If not,
* additional exchanges will be made.
*
* <p>Then, the remote ticketing processing must prepare all the commands of the session (from
* opening to closing) before executing it.
*
* <p>Example:
*
* <pre>{@code
* transaction
* .prepareOpenSecureSession(...)
* .prepare...
* [...]
* .prepare...
* .prepareCloseSecureSession()
* .processCommands(...);
* }</pre>
*
* <b>Caution</b>: this feature will be ineffective in the following cases:
*
* <ul>
* <li>the card or the SAM does not support the extended mode
* <li>the session contains commands that necessarily require exchanges with the card during the
* session (e.g. PIN, Stored Value, encryption, early mutual authentication, data not
* previously read outside the session)
* <li>the session is opened with an access level different from the pre-opening one
* <li>an intermediate "processCommand(...)" call has been made
* <li>the session uses asymmetric cryptography
* </ul>
*
* @param writeAccessLevel The write access level.
* @return The object instance.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -706,9 +706,12 @@ CardTransactionManager prepareDecreaseCounters(
* Schedules the execution of a <b>SV Reload</b> command to increase the current SV balance and
* using the provided additional data.
*
* <p>Note #1: a communication with the SAM is done here.
* <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
* <p>Note #2: the key used is the reload key.
* <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
* CalypsoCard#getSvLoadLogRecord()}.
*
* <p>Note #1: the key used is the reload key.
*
* @param amount The value to be reloaded, positive or negative integer in the range.
* -8388608..8388607
Expand All @@ -732,11 +735,14 @@ CardTransactionManager prepareDecreaseCounters(
/**
* Schedules the execution of a <b>SV Reload</b> command to increase the current SV balance.
*
* <p>Note #1: the optional SV additional data are set to zero.
* <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
* <p>Note #2: a communication with the SAM is done here.
* <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
* CalypsoCard#getSvLoadLogRecord()}.
*
* <p>Note #1: the optional SV additional data are set to zero.
*
* <p>Note #3: the key used is the reload key.
* <p>Note #2: the key used is the reload key.
*
* @param amount The value to be reloaded, positive integer in the range 0..8388607 for a DO.
* action, in the range 0..8388608 for an UNDO action.
Expand All @@ -763,9 +769,12 @@ CardTransactionManager prepareDecreaseCounters(
* previous debit according to the type operation chosen in when invoking the previous SV Get
* command.
*
* <p>Note #1: a communication with the SAM is done here.
* <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
* <p>Note #2: the key used is the reload key.
* <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
* CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
*
* <p>Note #1: the key used is the debit key
*
* @param amount The amount to be subtracted or added, positive integer in the range 0..32767 when
* subtracted and 0..32768 when added.
Expand Down Expand Up @@ -793,18 +802,14 @@ CardTransactionManager prepareDecreaseCounters(
* <p>It consists in decreasing the current balance of the SV by a certain amount or canceling a
* previous debit.
*
* <p>Note #1: the optional SV additional data are set to zero.
* <p>Once this command is processed, the SV data is updated in {@link CalypsoCard}.
*
* <p>Note #2: a communication with the SAM is done here.
*
* <p>Note #3: the key used is the reload key.The information fields such as date and time are set
* to 0. The extraInfo field propagated in Logs are automatically generated with the type of
* transaction and amount.
* <p>See the methods {@link CalypsoCard#getSvBalance()}, {@link
* CalypsoCard#getSvDebitLogLastRecord()}, {@link CalypsoCard#getSvDebitLogAllRecords()}.
*
* <p>Note #4: operations that would result in a negative balance are forbidden (SV Exception
* raised).
* <p>Note #1: the optional SV additional data are set to zero.
*
* <p>Note #5: the key used is the debit key
* <p>Note #2: the key used is the debit key
*
* @param amount The amount to be subtracted or added, positive integer in the range 0..32767 when
* subtracted and 0..32768 when added.
Expand Down Expand Up @@ -1275,7 +1280,7 @@ CardTransactionManager prepareChangeKey(
*
* <p>Note that if the next prepared command is a "Read One Record" or "Read One Or More
* Counters", then it will by default be merged with the "Open Secure Session" command for
* optimization purposes.
* optimization purposes except if the "pre-open" mode is active.
*
* <p>This mechanism may in some cases be incompatible with the security constraints and can be
* disabled via the {@link CardSecuritySetting#disableReadOnSessionOpening()} method.
Expand All @@ -1290,6 +1295,8 @@ CardTransactionManager prepareChangeKey(
* <li>A secure session is already opened
* </ul>
*
* @see
* org.calypsonet.terminal.calypso.card.CalypsoCardSelection#preparePreOpenSecureSession(WriteAccessLevel)
* @since 1.6.0
*/
CardTransactionManager prepareOpenSecureSession(WriteAccessLevel writeAccessLevel);
Expand Down

0 comments on commit f28a6e9

Please sign in to comment.