From bf796888bd65672d19b0580c772c876043de9b81 Mon Sep 17 00:00:00 2001 From: Pierre Terree Date: Sun, 3 Nov 2024 11:39:25 +0400 Subject: [PATCH] comment embedded session --- .../calypso-layer/calypso-card-api.md | 30 +++++++++++++++++-- ...n_optimized_embedded_sequence_diagram.puml | 10 +++++-- ...on_optimized_embedded_sequence_diagram.svg | 2 +- 3 files changed, 35 insertions(+), 7 deletions(-) diff --git a/content/specifications/calypso-layer/calypso-card-api.md b/content/specifications/calypso-layer/calypso-card-api.md index 020d54e..239d106 100644 --- a/content/specifications/calypso-layer/calypso-card-api.md +++ b/content/specifications/calypso-layer/calypso-card-api.md @@ -79,9 +79,33 @@ Calypso library. This example illustrates the ticketing processing of a validation: only the necessary data is read from the card. -In case of communication failure with the card, to support a recovery transaction on another terminal: the ratification -status and the last event are checked at the session opening, and the session is closed as not ratified directly -followed by a ratification command. +For access control to a transit network or a building, using a contactless card to authenticate the holder's rights, ticketing terminals are generally automatic machines for which the rights verification transaction is automatically launched when the contactless card is detected in the RF field emitted by the terminal's reader. For transactions to run smoothly, without the need for error recovery, it is important that the contactless transaction with the card is very fast, and that the card presentation and withdrawal detection phases are reliably managed. + +The aim is to save milliseconds by minimizing the volume of data transmitted during contactless communication with the card to complete the ticketing transaction.
+In order to limit the amount of data to be read from the card to the strict minimum, card reading operations cannot be grouped together. Each card response needs to be analyzed, to determine whether the next reading operation is necessary. Reducing the volume of data transmitted by the contactless card reader also reduces the amount of data to be transmitted to the SAM reader during the session, in order to update the session hash calculation.
+On the SAM side, it is necessary to: +- limit the number of operations to be performed during the contactless card transaction: SAM challenge recovery can be anticipated before a card transaction. +- group as many SAM exchanges as possible to be processed during the session (to counteract contact reader latency, and to share an APDU command header with a maximum amount of data to be transmitted) + +It is therefore necessary to anticipate card responses to write commands (counter increment/decrement). Under these conditions, only one group of SAM commands is needed during the card transaction to generate the SAM session MAC. Card authenticity verification can be performed while waiting for card removal. + +The contactless reader of a configured and active ticketing terminal can switch between 3 states: +- in '*standby mode*', the reader is waiting for a new card to be detected. +- when a card is detected, the reader is in card '*processing mode*'. +- when the card transaction is completed, the reader is '*waiting for the removal*' of the card. + Following a card transaction, a terminal must be sure that the card has indeed been removed from the RF field, before considering detecting a new one. + +For this reason, a terminal cannot be confident of a timeout at the transaction completion, as this timeout will either be too short (the previous card still present will be grabbed again) or too long (the terminal will remain unavailable for a long time). The contactless reader shall notify the withdrawal of the card. + +For a ticketing transaction during which card data is updated (right decrementation, memorization of an event), the “ratification” mechanism supported by the Calypso secure session guarantees that the cardholder will not lose any rights if the RF transmission with the card is interrupted.
+When a session is opened, the verification of a last ticketing event makes it possible to identify whether a card has been presented twice in quick succession on an access control line.
+In the case of very recent event, the card's “unratified” status can be used to determine whether +- whether it is a recovery transaction, for which it may be necessary to re-authenticate the cardholder without debiting new rights; +- or if it is an attempt to obtain a second access for another person (anti-passback). + +When a session is closed, the ratification command is immediately transmitted to the card, to minimize the need for transaction recovery. + + {{< figure src="/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.svg" caption="Calypso Card API - Simple Secure Session - Sequence Diagram" >}} diff --git a/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.puml b/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.puml index 075771a..1a9e0b0 100644 --- a/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.puml +++ b/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.puml @@ -139,7 +139,7 @@ deactivate rapi app->app: **wait** for card presence -== Card selection & identification == +== Access Control operation start\nCard selection & identification == cardReader<[#Orange]-? : card **insertion** . . . . . @@ -396,13 +396,15 @@ card in state: **ratified** endhnote +cardReader-[#0000FF]->capi: [card certificate] +deactivate cardReader + hnote over cardReader #Orange reader in state: **Wait For Card Removal** endhnote -cardReader-[#0000FF]->capi: [card certificate] -deactivate cardReader +== End of the contactless card transaction == capi-[#00FF00]>samReader: **SAM #2**\ntransmit card request\n\t- APDU list activate samReader #lightGreen @@ -418,6 +420,8 @@ deactivate capi app->app: card successfully authenticated <:champagne:> app->? : notification & **access granting** +== End of the Access Control opertion == + app->capi: **init** crypto context for next transaction activate capi #lightBlue diff --git a/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.svg b/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.svg index ab430e5..79747cd 100644 --- a/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.svg +++ b/static/media/specifications/calypso_transaction_regular_secure_session_optimized_embedded_sequence_diagram.svg @@ -1 +1 @@ -Ticketing ApplicationTicketing ApplicationReader APIReader APICalypsoCard APICalypsoCard APICalypso CardReaderCalypso CardReaderCardCardCalypso SAMAPICalypso SAMAPICalypso SAMReaderCalypso SAMReaderSAMSAMAccess Control embedded Terminal settingssetCalypso SAM libpreparecard selection:- filter by Power-On datapreparecard selection scenario:- legacy SAM selectionprocesssynchronous card selection scenarioSAM #xtransmit selection request- card selectoropen card channelreceive selection responseThe SAM remains permanently selected between card transactions.selected active SmartCard imagecastSAM card[legacy SAM image:- identification data]Apart from SAM module selection, a secure transaction witha Calypso card is managed independently of the SAM API.initcrypto context for next transactionSAM #x'transmit card request- APDU listget challenge[SAM challenge][SAM challenge]preparecard selection:- filter by specific AID- filter invalidated card statuspreparecard selection scenario:- Calypso card selectionscheduleasynchronous card selection scenarioaddobserverstart detection- repeating modereader in state:Wait For Card Insertionwaitfor card presenceCard selection & identificationcardinsertion. . . . .reader in state:Wait For Card ProcessinginsertionCard #1transmit selection request- card selectoropen card channelselect application (aid)[card FCI]checks invalidation statusreceive selection responsenotifyscheduled card selections responseeparsescheduled card selections responseselected active SmartCard imagecastCalypso card[Calypso card image:- identification data- invalidation status]Card secure transactioninstantiateCalypso card transaction:- Calypso card resource- Calypso SAM resourceOnly reads data inside the session.preparecard transaction:- open secure session (DEBIT access level)- read environment fileprocesscommands (keepchannel open)SAM challenge already knownno need to request it duringthe card transactionCard #2transmit card request- APDU listCard APDU commands inside sessionOptimization: environment file read through the session opening.open secure session (card debit key,SAM challenge,SFI environment to read)[card challenge & environment data][card challenge]checks ratification statuscard in state:ratified[Calypso card image:- identification data- invalidation status- environment data- ratification status]preparecard transaction:- read last eventprocesscommands (keepchannel open)Card #3transmit card request- APDU listCard APDU commands inside sessionread record (last event)[last event data][last event data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data]checks transaction recovery statuspreparecard transaction:- read contract listprocesscommands (keepchannel open)Card #4transmit card request- APDU listCard APDU commands inside sessionread record (contract list)[contract list data][contract list data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data]identifies contractpreparecard transaction:- read contract #xprocesscommands (keepchannel open)Card #5transmit card request- APDU listCard APDU commands inside sessionread record (contract #x)[contract #x data][contract #x data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data- contract #x data]identifies associated counterpreparecard transaction:- reader counter #xprocesscommands (keepchannel open)Card #6transmit card request- APDU listCard APDU commands inside sessionread record (counter #x)[counter #1 data][card challenge][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data- contract #x data- counter #x data]defines data to updateprepare:- decrease counter #x (new value)- append event record (new event)- close secure session (not ratified)processcommands (closechannel after)anticipates the future card responsesIf the current value of the counter #x wereunknown, then the transmission of an additional card APDUmessage would be necessary to operate the decrease counter in a different message than the session closing.SAM #1transmit card request- APDU listAll card session data managed within a single SAM command group.select diversifier (card serial)digest init (opening data)digest update (read environment)digest update (last event)digest update (read contract list)digest update (read contract #x)digest update (read counters) anticipatedCard APDU responsesdigest update (decrease counter)digest update (append event record)digest close[SAM certificate][SAM certificate]Card #7transmit card request- APDU listCard APDU commands inside sessiondecrease counter (counter #1, value)[new counter value]append record (event, data)close secure session (SAM certificate,asnon-ratified)[card certificate]card in state:non-ratifiedratification command immediately performed after session closingratification commandcard in state:ratifiedreader in state:Wait For Card Removal[card certificate]SAM #2transmit card request- APDU listdigest authenticate (card certificate)[authentication status][authentification status][Calypso card image:- identification data- invalidation status- environment data-ratification status- last event data (updated)- contract list data- contract #x data- counter #x data (updated)]authentification statuscard successfully authenticatednotification &access grantinginitcrypto context for next transactionSAM #x'transmit card request- APDU listget challenge[SAM challenge][SAM challenge]waitfor card removalcardremoval. . . . .reader in state:Wait For Card Insertionremovalready for next card transaction \ No newline at end of file +Ticketing ApplicationTicketing ApplicationReader APIReader APICalypsoCard APICalypsoCard APICalypso CardReaderCalypso CardReaderCardCardCalypso SAMAPICalypso SAMAPICalypso SAMReaderCalypso SAMReaderSAMSAMAccess Control embedded Terminal settingssetCalypso SAM libpreparecard selection:- filter by Power-On datapreparecard selection scenario:- legacy SAM selectionprocesssynchronous card selection scenarioSAM #xtransmit selection request- card selectoropen card channelreceive selection responseThe SAM remains permanently selected between card transactions.selected active SmartCard imagecastSAM card[legacy SAM image:- identification data]Apart from SAM module selection, a secure transaction witha Calypso card is managed independently of the SAM API.initcrypto context for next transactionSAM #x'transmit card request- APDU listget challenge[SAM challenge][SAM challenge]preparecard selection:- filter by specific AID- filter invalidated card statuspreparecard selection scenario:- Calypso card selectionscheduleasynchronous card selection scenarioaddobserverstart detection- repeating modereader in state:Wait For Card Insertionwaitfor card presenceAccess Control operation startCard selection & identificationcardinsertion. . . . .reader in state:Wait For Card ProcessinginsertionCard #1transmit selection request- card selectoropen card channelselect application (aid)[card FCI]checks invalidation statusreceive selection responsenotifyscheduled card selections responseeparsescheduled card selections responseselected active SmartCard imagecastCalypso card[Calypso card image:- identification data- invalidation status]Card secure transactioninstantiateCalypso card transaction:- Calypso card resource- Calypso SAM resourceOnly reads data inside the session.preparecard transaction:- open secure session (DEBIT access level)- read environment fileprocesscommands (keepchannel open)SAM challenge already knownno need to request it duringthe card transactionCard #2transmit card request- APDU listCard APDU commands inside sessionOptimization: environment file read through the session opening.open secure session (card debit key,SAM challenge,SFI environment to read)[card challenge & environment data][card challenge]checks ratification statuscard in state:ratified[Calypso card image:- identification data- invalidation status- environment data- ratification status]preparecard transaction:- read last eventprocesscommands (keepchannel open)Card #3transmit card request- APDU listCard APDU commands inside sessionread record (last event)[last event data][last event data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data]checks transaction recovery statuspreparecard transaction:- read contract listprocesscommands (keepchannel open)Card #4transmit card request- APDU listCard APDU commands inside sessionread record (contract list)[contract list data][contract list data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data]identifies contractpreparecard transaction:- read contract #xprocesscommands (keepchannel open)Card #5transmit card request- APDU listCard APDU commands inside sessionread record (contract #x)[contract #x data][contract #x data][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data- contract #x data]identifies associated counterpreparecard transaction:- reader counter #xprocesscommands (keepchannel open)Card #6transmit card request- APDU listCard APDU commands inside sessionread record (counter #x)[counter #1 data][card challenge][Calypso card image:- identification data- invalidation status- environment data- ratification status- last event data- contract list data- contract #x data- counter #x data]defines data to updateprepare:- decrease counter #x (new value)- append event record (new event)- close secure session (not ratified)processcommands (closechannel after)anticipates the future card responsesIf the current value of the counter #x wereunknown, then the transmission of an additional card APDUmessage would be necessary to operate the decrease counter in a different message than the session closing.SAM #1transmit card request- APDU listAll card session data managed within a single SAM command group.select diversifier (card serial)digest init (opening data)digest update (read environment)digest update (last event)digest update (read contract list)digest update (read contract #x)digest update (read counters) anticipatedCard APDU responsesdigest update (decrease counter)digest update (append event record)digest close[SAM certificate][SAM certificate]Card #7transmit card request- APDU listCard APDU commands inside sessiondecrease counter (counter #1, value)[new counter value]append record (event, data)close secure session (SAM certificate,asnon-ratified)[card certificate]card in state:non-ratifiedratification command immediately performed after session closingratification commandcard in state:ratified[card certificate]reader in state:Wait For Card RemovalEnd of the contactless card transactionSAM #2transmit card request- APDU listdigest authenticate (card certificate)[authentication status][authentification status][Calypso card image:- identification data- invalidation status- environment data-ratification status- last event data (updated)- contract list data- contract #x data- counter #x data (updated)]authentification statuscard successfully authenticatednotification &access grantingEnd of the Access Control opertioninitcrypto context for next transactionSAM #x'transmit card request- APDU listget challenge[SAM challenge][SAM challenge]waitfor card removalcardremoval. . . . .reader in state:Wait For Card Insertionremovalready for next card transaction \ No newline at end of file