Requirements on content provider API

This article is valid for Smart ID Mobile App 5.4 and Smart ID Mobile SDK 3.0.0 (for iOS) and Hermod 3.1.1 and later.

This article describes requirements on a content provider that shall be used to store authentication images or card layout images for mobile virtual smart cards in Smart ID Mobile App.

General requirements

To use a content provider with Hermod, to provide authentication images or card layout images on a mobile virtual smart card, the following requirements apply:

The connection to a content provider must be set up in the Hermod client. See Add API user and callback URL in Hermod.
The content provider must have an API, according to the specification below.
For a visual smart card backside, the format is JWS which must be signed by certificates given out by Nexus. Contact Nexus for more information.

POST /getcontent

The content provider API must include a POST request for getting the image data, according to this specification.

Method

POST

Body

The content provider API must accept the following JSON data, where the contentId value can for example be a <uuid>:

Example: POST /getcontent command

CODE

{
   "contentId":"67d21afb-e830-4fee-a691-00a997ffbe1a"
}

Recommendation

To simplify the implementation of the content provider service, "contentId" can also define the specific use case, by combining the unique identifier <uuid> with another string, such as "PROV:<uuid>" for provisioning mobile virtual smart cards with visual ID and "AUTH:<uuid>" for authentication images.

Example response for card layout images

The content provider API must return an array with one or two elements representing the front and back images of the card. The format is as follows:

Example response

CODE

{
   "data":[
      {
         "content_encoding":"base64",
         "content_type":"image/jpeg",
         "key":"front",
         "data":"VmVyaWZpZXJh......ZW4gw6RyIHLDpHR0"
      },
      {
         "content_encoding":"text/plain",
         "content_type":"application/jose",
         "key":"back",
         "data":"HEADER.PAYLOAD.SIGNATURE"
      }
   ]
}

The value in key must match the value of "key" in the visualData section in the Hermod API provisioning message, that is, "key":"front" or "key":"back". See example in Provision mobile virtual smart card with visual ID.

The front data can be either the base64 encoded image data or a JWS containing the image data.
The back data must always be in JWS format and signed with certificates given out by Nexus.

The JWS must contain the certificate chain used for signing, the algorithm and an exp field indicating when the card image will be labeled as expired.

Example: JWS structure

CODE

JWS HEADER:

    {
      "x5c": [
        "LEAF_CERT_DATA",
        "INTERMEDIATE_CERT_DATA",
        "ROOT_CERT_DATA"
      ],
      "exp": EPOCH_FOR_IMAGE_EXPIRATION,
      "alg": "RS256 OR RS512"
    }

JWS PAYLOAD:

    "BASE64_ENCODED_IMAGE"

SIGNATURE:

    "xxxxx"

Example response for authentication images

The content provider API must return the following JSON data:

Example response

CODE

{
   "data":[
      {
         "content_encoding":"base64",
         "content_type":"image/jpeg",
         "key":"auth_image",
		 "visible":true,
         "data":"VmVyaWZpZXJh......ZW4gw6RyIHLDpHR0"
      }
   ]
}

The value in key must match the value of "key" in the description section in the Hermod API authenticate message, that is, "key":"auth_image" . See example in Use authentication images from a content provider service.