Introduction

Principles

The Server-Side Middleware relies on the client-side SCWS architecture. The regular SCWS API is used to obtain the smart card readers, and connect to the card. The client-side SCWS API can also be used to perform preliminary checks and analysis of the card, without involving the server yet. Then, when an operation that requires direct communication between the server and the card needs to be performed, a “server session” is opened. During this session, all operations with the card are directly under control of the server, and the client middleware only serves as a relay for the APDU commands that must be sent to the card. When the session closes, the client-side can eventually take control on the card again.

There is no assumption made by the middleware regarding the card operations that must be made on the client side and the operations that must be made on the server side. All the operations are available on both side, and it is up to the application developer to decide what should be done on either side. There may be secrets that should stay on the client side (typically PINs), and secrets that should stay on the server side (typically secure channel keys). Depending on what is being done, the developer has the choice to perform the operation where is makes sense. However, note that some context-dependent state (PIN verification status, secure channel session, …) will be lost when switching from client-side operations to server-side operations, or the other way around. Moreover, all cached data is invalidated (which may lead to a performance penalty) when switching side, to ensure that any potential modification made on the card from the other side will be taken into account.

In addition to the necessary requirements on the server for using the regular SCWS API (HTTP entry point for the signature of a challenge, to perform the proprietary authentication scheme), there is an additional prerequisite for the Server-Side Middleware: having a specific server session processing HTTP entry point on the server (no assumption is made on its path and name) that will relay incoming requests from the clients to a dedicated entry point in the Server-Side Middleware API (see SCSSSession.process). This is used to implement the APDU command relay mechanism.

Architecture

The Server-Side Smart Card Middleware is structured as shown below:

Operation

When a server session needs to be opened, the following operations must be made:

• Create a new SCSSSession instance on the server-side. For each SCSSSession, a handle (character string identifying the session) is internally generated. At this stage, the session is not yet bound to a specific client.

• Retrieve the session handle and send it to the client.

• At this point, there are two operations that must be processed in parallel:

  • Call the Token.processServerSession() method from the client-side JavaScript code. This method is taking care of the APDU command relaying, and will regularily call the session processing HTTP entry point on the server (this allows the client-side to fetch the card command sequences to be executed).

  • Run the server-side operations to perform through the SCSSSession instance. This will typically be triggered from the client-side by calling a custom REST entry-point on the server. The SCSSSession.init method must be called first. Then any method from the Token class, from which the SCSSSession class inherits, and which contains all required methods to interact with the card, can be called. These methods are very similar to the client-side SCWS JavaScript API.

During the entire time the server session is opened, the smart card is under exclusive control of the server, to ensure that the sequence goes uninterrupted, and that volatile status (secure channels, selection state, …) is not altered by other processes potentially trying to access the smart card concurrently. It is therefore recommended to keep the session opened for as little time as required, because a server session would prevent other applications to use the smart card.

You should also make sure that no operation through the client-side SCWS API is made during the entire time the server session is active. Mixing client-side operations within a server session could lead to cached data inconsistencies and deadlocks.

When the operations are done, SCSSSession.close needs to be called from the server-side. This will terminate the server session on the server-side and remotely trigger the closing on the the client-side too. The session on the client-side is effectively closed when the promise returned by Token.processServerSession() is resolved. This should be the event to wait for if there are further client-side operations to be made through the SCWS JavaScript API.

Here is a typical sequence diagram showing how sessions are opened and closed:

Notice how the session is not effectively closed before the processServerSession promise resolves. When the operation REST entry point returns, the session is closed on the server side, but may still be live on the client side for a very short time (until the session processing mechanism can notify the client that the session has been closed).