Gimly SSI Card Terminal

Gimly SSI Card Terminal is a REST API for Self Sovereign Identity interactions between apps, servers, terminals having an NFC reader and NFC cards.

The API is used as an easy integration means for Desktop, Terminal and Server environments equipped with a NFC reader. The API is targeted at Self Sovereign Identity and Authentication use cases, meaning it can be used to create asymmetric keys for Decentralized Identifiers, as well as store and present Verifiable Credentials and Verifiable Presentations. Given the private key is securely stored in the NFC cards protected environment, it means the solution provides security for SSI use cases on desktop and terminal environments which typically would not be possible otherwise.

API Documentation

The below examples are the most common use cases.

The full API documentation including all endpoints can be found here

To view the API definition online open editor.swagger.io

Scanning a card

To start working with the NFC card, you typically have to scan the card first

Simply doing a GET call to the root / will return basic NFC card information once you tapped the NFC card to the reader.

scanCard

CardInfoResult scanCard()

Parameters

This endpoint does not need any parameter.

Return type

CardInfoResult

Creating a key(pair) on the NFC card

This creates an asymmetric keypair on the NFC card. The private key will never be disclosed and is safely stored in the card. The public key is disclosed. The key can be used as a regular keypair, not using DIDs at all if desired. To access and use the key later you can use the public key value, its card index or the DID Key id value

createKey

KeyResults createKey(cardId, CreateKeyRequest)

Parameters

Return type

KeyResults

Sign using the key on the NFC card

This method allows you to sign one or more inputs using the private key stored on the NFC card.

signUsingKey

SignResponse signUsingKey(keyId, SignRequest, cardId)

Parameters

Return type

SignResponse

Add a proof to a credential

This method adds a proof to the supplied credential, using the private key on the NFC card and thus making it a Verifiable Credential. It allows for optional storage of the VC on the NFC card.

signCredential

SignCredentialResponse signCredential(keyId, SignCredentialRequest, cardId)

Parameters

Return type

SignCredentialResponse

Add a proof to a presentation

Sign ths supplied presentation using the key on the NFC card, adding a proof and making it a verifiable presentation. Please note that verifiable presentations cannot be stored, as the nature of Verifiable Presentations is to use them on singular invocations only

signPresentation

SignPresentationResponse signPresentation(keyId, SignPresentationRequest, cardId)

Signs a presentation (adds a proof)

Parameters

Return type

SignPresentationResponse

Get all Verifiable Credentials stored on the NFC card

Verified Credentials that are self-issued as well as externally issued with a subject that related to the NFC card, can be stored on the NFC card. This method returns all stored Verifiable Credentials.

getStoredCredentials

StoredCredentialsResponse getStoredCredentials(cardId)

Parameters

Return type

StoredCredentialsResponse

TODO

• Mock testing once we have the latest cards
• Auth support on the endpoints itself
• Integration with GraalVM for native executables
• Windows service integration
• Docker support with USB?
• Do we want direct DID creation support, instead of external application created DIDs and only KID resolution?
• SDK generation for popular languages