This specification defines a protocol that allows a Device Application to request the management of a Secure Element by a Management Platform.
The following figure presents the global architecture of GP SERAM and its environment. All words in blue are defined in this specification.
In this architecture, a Remote Agent and a Local Agent manage this protocol to allow the Management Platform to interact with a Device Application and the Secure Element.
While Management Platform, Device and Secure Element are physical entities, the Device Application and Core Management Platform are logical components, and the Remote Agent and the Local Agent in this specification are to be considered as functions. These functions might be implemented as standalone applications or as libraries integrated inside larger business applications. In the GP SERAM context, the terms Remote Agent and Local Agent may be used interchangeably with Remote Agent function and Local Agent function.
Note that if the Device embeds a Trusted Execution Environment, the Local Agent may be implemented in this Trusted Execution Environment. Otherwise, the Local Agent is implemented in the Rich Execution Environment of the Device. In these two cases, the Local Agent will have to use an API providing access to the Secure Element and allowing it to forward commands to an application in this Secure Element. This API is called an SE Access API in this specification. The SE Access API can be the SIMalliance GlobalPlatform Open Mobile API when the Local Agent is implemented in the Rich Execution Environment (REE), and the GlobalPlatform TEE Secure Element API when the Local Agent is implemented in the Trusted Execution Environment (TEE).
More precisely, an SE Access API usually provides mechanisms for a device application to open a connection with the Secure Element and then to open a logical channel with a card application in order to send APDUs to this application.
GP SERAM is a message-oriented protocol which used the following protocol stack:
Messages are the data exchanged between the Remote Agent and the Local Agent. The definition, the meaning and sequency of Messages are states below in the Messages section.
How Messages are carried on the network relies on the Protocol Binding used by the Remote Agent and the Local Agent. A Protocol Binding defines the rules to map Messages on the Data Format layer and the Transport layer.
This version of the specification defines the following Data Format and Transport protocol layers:
-
HTTPS as Transport
-
JSON as Data Format
Others protocol layer elements may be defined in the future.
This version of the specification defined the following Protocol Binding:
- HTTP REST, which uses HTTPS as Transport protocol and JSON as Data Format.
Others Protocol Binding may be defined in the future.
A Device Application and a Management Platform relies on a session identifier, named sessionId. The sessionId is shared and used for all communications between the Remote Agent and the Remote Agent.
The session during which is performed some management tasks that are associated with one sessionId is called the Management Session.
In term of GP SERAM protocol, the Management Session is started by the triggering of the Local Agent by the Device Application and is then controlled until its end by the Remote Agent.
As shown by the next figure, this protocol has three steps. First the Local Agent is triggered by the Device Application with the sessionId and the RA Endpoint. It then negotiates the Data Format and Transport protocol to use with the Remote Agent. Finally, the Remote Agent make the task required for the Management Session.
Most of the Initialization Step is out of the scope of this document.
During the Handshake Step, the Local Agent performs a protocol negotiation with the Remote Agent, by sending its capabilities, the session identifier, and a list of manageable Secure Element. A Protocol Binding to be used for the next step is then selected.
Next, the Management Platform starts a Command Exchange Step by sending a Start Command. During the Command Exchange, the Management Platform may send APDUs to the Secure Element, or send notifications to the Device Application. The end of the Management Session is announced by a Stop Command form the Management Platform.
During this phase, a session identifier, named sessionId, SHALL be generated and shared between the Device Application and the Management Platform. How, when, and by whom this sessionId is generated is out of the scope of this specification and it just needs to be understandable by the Management Platform.
The sessionId SHALL be a unique identifier for the Device Application and the Management Platform. How this uniqueness is handled is out of the scope of this specification.
Moreover, the RA Endpoint to communicate with the Remote Agent MUST also be shared between entities. How this RA Endpoint is defined and shared is out of the scope of this specification.
The GP SERAM Management Session starts after the Local Agent is triggered with the sessionId and the RA Endpoint of the Remote Agent. Then, the Local Agent starts with the Handshake Step.
As soon as it was triggered, the Local Agent shall start the Handshake Step.
Handshaking allows a Local Agent and Remote Agent to negotiate the Data Format and the Transport protocol used to perform the remote management.
This method shall be used by the Local Agent to tell which Data Format and which Transport protocols it supports. In response, the Remote Agent shall tell which ones it selects.
The attributes which are negotiated are:
-
The secure elements: the Local Agent provides a list of Secure Element which may be targeted by the Remote Agent
-
The Data Format (e.g. JSON)
-
The Transport protocols (e.g. HTTPS)
-
The version of the protocol
To allow the Remote Agent to track the Command Exchange the Local Agent provides a sessionId that shall be reused in all subsequent exchanges as defined by the selected Protocol Binding.
The Handshake Step shall be performed using the HTTP REST Protocol Binding.
During the Command Exchange Step, the Remote Agent performs a series of actions by sending Commands to the Local Agent. The Local Agent processed each Command and if required send a Response to the Remote Agent.
Commands and Responses are exchanged using, respectively, Order Messages and Report Messages. An Order Message sent by the Remote Agent may carry one or more Command. Similary, a Report Message from the Local Agent may carry one or more Response. Messages which are exchanges during the Command Exchange Step shall use the Protocol Binding which has been selected during the Handshake Step.
As shown by the diagram, the first and last Command of the Command Exchange Step is respectively the Start Command and Stop Command. Other RAM Commands are used to send APDUs to the Secure Element, or Notifications to the Device Application. Only the Start and Stop Commands are mandatory.
The following sequence diagram resumes the main exchanges during a Management Session. In the diagram the exchanges during the Command Exchange Step are illustrated with the two types of RAM Command that can be sent by a Remote Agent after the Start Command and until the Stop Command.
The following type of Messages may be exchanged between Local Agent and Remote Agent:
| Protocol Step | Messages | From | To |
|---|---|---|---|
| Handshake | Handshake Command | Local Agent | Remote Agent |
| Handshake | Handshake Response | Remote Agent | Local Agent |
| Command Exchange | Order | Remote Agent | Local Agent |
| Command Exchange | Report | Local Agent | Remote Agent |
As soon as triggered, the Local Agent starts the Handshake Step by sending a Handshake Command Message to the Remote Agent with the a list of manageable Secure Element.
On reception of the Handshake Response Message from the Remote Agent, the Local Agent goes to the next Command Exchange Step using the selected Protocol Binding. During this Step, the Local Agent proceeds the Command from Order Messages one-by-one and, if required, it appends the associated Response into Report Messages. As the first Command shall be a Start and the last one a Stop, the internal state machine of the Local Agent is detailed in the next figure:
On Notification Command the Local Agent shall sent a notification to the Device Application. How the Device notify the Device Application and its reliability is implementation dependent. Notification Command do not require Response, nor a state change.
On SE RAM Command the Local Agent shall send each C-APDU to the selected Secure Element according with the SE Access API and add the R-APDU to the SE RAM Response. If the C-APDU is a SELECT Command as defined by GP Card Specification, the SE Access API, may required the Local Agent to use a dedicated function to open a logicial channel with the Secure Element. This logicial channel shall be used for the subsequent C-APDU and closed if another SELECT Command is received or at the end of the Management Session. On any error to transmit the C-APDU, the Local Agent shall discard all the remaining C-APDU and shall not include any R-APDU in the response for the faulty transmission. The Local Agent do not need to parse and handle R-APDU. Any warning or error R-ADPDU (i.e. those with a 69xx or 68xx status word) are valid R-APDU that shall be added to the SE RAM Response.