Purpose

 OpenAPI Documentation

The BoB-standard was initially released with ideas of additional/optional ways of handling ticket information and bearers. It resulted in the concept "ID-based travelling" - travelling with only a reference to the actual ticket information and its validity. 

• The travel document holds only a reference ID to the actual ticket and its information which is stored within the ticketing service. The actual ticket and the validity of a users entitlements to travel is independent of a physical ticket bearer.

• Traveller does not physically carry any ticket information and the validity/right to travel - just a reference to it through an ID in a physical bearer (a token).

• Validation service only interprets an ID (as a reference) from the travel document and sends a request about validity to the ticketing service.

• The maintenance of the ticket information and its entitlements may be more easily handled within an account in back-end system than a ticket in a bearer. This is especially true for travel cards, which are infrequently connected.

• Each travel document is unique since the token ID is generated from a cryptographic key (refer to MTS7 for details around cryptographic keys and ID derivation). The same Token ID (i.e. the same public-private key pair) must only reside in one physical bearer. It is the issuer of the token which is responsible to ensure the keys can not be extracted from the bearer.
• The token has to be registered with each sales function the traveller wishes to use. In a true BoB world the traveller would only have to register it with the preferred sales function, and through that be able to use the whole national network of public transport.
• How the token is generated, issued and delivered to the traveller is outside of the scope of the specifications.
• A traveller may register as many Travel Documents (tokens) as he or she wishes. Under normal circumstances, business rules will only allow a ticket to be bound to one of these tokens at the same time. There may also be restrictions on how many times during a certain time frame a ticket can be handed over or lended. This as to prevent sharing of a travel pass between many people in different places. This is however something each Public Transport Authority will enforce.

Definitions

An object (plastic card, wearable, app in mobile phone etc.) that carries a physical or emulated PICC (Proximity Integrated Circuit Card) in which a Travel Card Application is run which consists of a so called Travel Document also referred to as MTB (Mobile Ticket Bundle) is in its total the physical bearer for which the validity to travel is formed.

When the concept Travel Document is used it is the above distinction that is referred to.

For implemenentation and documentation details for each API request described on this page please see OpenAPI specifcation for that specific API.

BoB Token API

•  token.yaml

The new Token API is used for retrieving information relating to tokens from the issuer. Its main function is to return the token public key given a serial number or tokenId. It is also used for retrieving revocation information.

A token may be revoked by the issuer, either by request of the holder or for other (unspecified) reasons, such as mis-use. A revocation entry SHOULD have an expire time. A token MAY be un-revoked by publishing a new previous revocation entry for the same tokenId with an expire set to current time. If the expire time is not given or if the expire time is set more than one year into the future, it MAY be truncated by the requester to one year counting from the time when the entry was retrieved from the Token API. This is to prevent the revocation information to take vast amount of resources from the Validation Service. It is always recommended to set the expire time of a revocation entry, and the Validation Service SHOULD only purge older entries as required to free system resources.

Additional API used (and adapted for ID based travelling/TokenAPI)

• validation.yaml
• inspection.yaml
• ticket.yaml
• participantmetadata.yaml

Added functionality in additional APIs related to ID-based travelling

Validation & Inspection APIs

The `tokenTransaction` property in events object in the Validation and Inspection APIs is used for ID-based travelling. This property includes an object representing the token public key (tpk) as well as the authentication input data (`aiData`), request (`aiRequest`) and response (`aiReponse`) sent to and received from the token during authentication.

Validation API

The Validation API features a `whitelist` containing entries of TICKLE entitlements (with validity period) associated with a token public key thumbprint. It is not mandatory to support the whitelist feature as validations can also be made using direct on-line calls to the validation API's. Inspectors are expected to use the corresponding on-line feature in the inspection API, but may also use the whitelist functionality if required.

The Blacklist functionality has been expanded to also include tokens (by tokenId).

Ticket API

The `tokenId` filter property in the `getAllTickets` operation if used for retrieving travelling entitlements tied to a token. This feature can be used at the time of validation to check wether the holder of the travel document is entitled to travel.

Likewise, in manifestCall and in ticketBundleRequest, a ticket or ticketBundle MAY be bound to a token. This is done by including the token public key in the protectedIssuerHeader of the MTB. For this reason, these calls require the full public key (not only the tokenId which is the thumbprint of the token public key). The tokenIssuer MAY also be given to enable ticketing to perform revocation checking before issuing the MTB. This, however, MAY also be left to the discretion of the validation service at the time of validation.

ParticipantMetadata API

Token has been added to the endpointDefinition. 

Below is an explanation in sequenced order of the different system interactions for the different scenarios a traveller is undertaking for a journey using ID based travelling.

Prerequisites

A prerequisites to this use case is that the traveller has requested a travel document and that the travel document issuer has delivered the travel document to the traveller. The travel document format can be in any of the following formats:

• Plastic card, wearable or other type of device with a proximity integrated circuit chip (PICC)
• Emulation of a PICC in an app (smart phone built-in wallet).
• An app in a device with NFC capability

In the case below the travel document is assumed to be a plastic card with a proximity integrated circuit chip (PICC). This card holds the BoB Travel Card application (defined in MTS7) with an MTB containing the Participant identifier (PID) of the card issuer and the public key of the card. The MTB on the card may otherwise empty. On the card the issuer has printed a cardnumber/serialnumber. The card contains the private key in a protected memory and is used for authentication at the time of validation.

There may be scenarios, e.g. where the travel document is represented by an emulated card in the electronic wallet of a smart phone or an app in such a device. In such cases, where the device holding the token is connected and may communicate with the sales function, it is recommended to mirror the travel entitlements into the MTB on the device, to enable more robust validation in times where communication with the underlying ticketing system is slow or intermittent. It may also be the case that the card is presented using a smartphone's built-in wallet functionality, in which case it may not be practical to regularly update the MTB. Then strict ID based travelling may apply even for connected devices.

Sequence Diagram

Sequence Steps

In this scenario, a traveller would like to purchase a ticket and tie it to a Travel Document (token) which the traveller already possess. How the traveller has acquired the Travel Document (token) is not described here, and may have occurred in any number of different ways.

1. The first step describes a scheduled iteration where the ticketing service regularly queries the Travel Document Issuer, via the Token API, for revoked tokens - this in order at a later stage not to tie any ticket to an invalid/withdrawn tokenID (travel document).
2. In the second step of the process the Travel Document Issuer responds with revocation information.
3. If not already done the first step before the ticket purchase sequence is to register the travel document in the sales channel, either by selecting the issuer of the token and typing in the serial/card number or by reading the card.
4. In cases where the serial number is used for registering the travel document, the Sales channel calls the Travel Document Issuer's Token API to retrieve the public key.
5. The token service returns the public key which is registered by the Sales Function.
6. Traveler uses Sales channel to select the desired product. This step involves calls to BoB Price and Product services as well as calls to payment service provider, which is not shown here.
7. The Sales function calls the ticketing service to request the issuance of a ticket valid for the selected product and to tie it to the provided public key for the travel document.
8. The ticketing service uses the provided Public key to look up the travel documents token ID towards the token revocation list. If token ID is not revoked then a ticket is issued and tied to the Travel document.
9. A confirmation response is returned to sales channel.
   
   Steps 10-15 depicts the scenario where whitelists are used to enable offline validation of tickets tied to tokens.
   
10. In step 10 the whitelist information is updated with the ticket tied to the token issued in step 8.
11. The vehicle on-board validation service regularly queries the back-end for updates to the whitelist.  
12. Updates are sent to the on-board validation service.
13. The traveler validates the travel document during boarding. The validation service authenticates the travel document using the public key provided within the cryptographically signed MTB, using the process defined in MTS7. The token ID is calculated using this public key provided by the card and subsequently used in the next step.
14. Validation service checks the token ID against the whitelist and validates any tickets tied to the token.
15. Validation event is sent to the back-end and registered.
    
    Steps 16-20 depicts the on-line scenario where whitelists are not needed.
    
16. The traveler validates the travel document during boarding. The validation service authenticates the travel document using the public key provided within the cryptographically signed MTB, using the process defined in MTS7. The token ID is calculated using this public key provided by the card and subsequently used in the next step.
17. Validation service calls the Ticket API to retrieve any valid tickets tied to the token. ID
18. Valid tickets tied to the token ID are sent back to the validation service.
19. The Validation service validates the provided tickets.
20. Validation event is sent to the validation back-end and registered.
    
    

Authentication procedure - Sequence steps 13 & 16

The BoB Travel Card Application defines a secure authentication procedure using asymmetric cryptography. For reasons of simplicity and scalability, the interface to the card is open and unencrypted. This eliminates the need of managing distributing access keys. The term card is used in the description, but the travel document can take any form as described above.

The authentication process is therefore the following:

1) The terminal (reader) selects the BoB application and, in response, also receives the other technical characteristics of the travel card (maximum APDU length supported, etc.). This also includes the cards serial number. However, these data are read in plain text and can not be trusted.

2) The terminal (given the parameters given in step 1) reads the MTB stored in the chip. In the Issuer Signature Protected Header (refer to MTS1 section 2.2) of the MTB the card's public key is stored. This information can be trusted because it is cryptographically signed by the issuer.

3) The terminal collects information that is to be included in the information to be digitally signed by the card in order to generate proof that a certain card has been used at a given time and place, and calculates a hash of this.

4) The terminal takes this hash and sends to the card's authentication function. The chip then makes a cryptographic signing operation with the private key embedded in protected (secure) memory of the card.

The response obtained is verified using the public key contained in the MTB Issuer Signature Protected Header. If the response can be successfully verified, the card has proved that MTB and card are connected and that the card is also genuine.

The response is retained together with the evidence compiled in step (3).