Gimly SSI-NFC SDK

Gimly SSI-NFC SDK is a kit Self Sovereign Identity interactions between react native apps having an NFC reader and NFC cards.

The SDK is used as an easy integration means for React Native applications equipped with an NFC reader. The SDK 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.

The current version of the SDK uses Tangem under the hood, which may require additional native changes documented here

Installation

yarn add gimly-ssi-nfc-react-native

Scanning a Card

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

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.wallet.scanCard().then(cardInfo => {
  // handle cardInfo
}).catch(error => {
  // handle error
})

Parameters

None

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

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.createKey(curve).then(keyInfo => {
  // handle keyInfo
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- curve | Curve | | Optional. Default to null.

Return type

KeyResults

Deactivating Key

Deactivate a key by card index, public key or DID key

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.deactivateKey(keyId).then(() => {
  // handle success
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- keyId | String | The Key index, public key or DID/Verification method key id |

Return type

None

Get Keys

Gets all keys by card id

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.getKeys(initialMessage).then(keyResults => {
  // handle success
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- initialMessage | String | The message to display |

Return type

KeyResults

Get a Single Key

Gets a key by card id and keyId

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.getKey(initialMessage, keyId).then(keyResults => {
  // handle success
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- initialMessage | String | The message to display | keyId | String| The Id of a key |

Return type

KeyResults

Signing 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.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.signUsingKey(signRequest, keyId).then(signResponse => {
  // handle sign response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- signRequest | SignRequest | Signs one or more inputs, typically hashes in hex format | keyId | String | The Key index, public key or DID/Verification method key id | Default to null.

Return type

SignResponse

Adding 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.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.signCredential(signCredentialRequest, keyId).then(signCredentialResponse => {
  // handle sign response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- SignCredentialRequest | SignCredentialRequest | Signs one or more inputs, typically hashes in hex format keyId | String | The Key index, public key or DID/Verification method key id | Default to null.

Return type

SignCredentialResponse

Adding a Proof to a Presentation

Sign the 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

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.ssi.signPresentation(signPresentationRequest, keyId).then(signPresentationResponse => {
  // handle sign response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- SignPresentationRequest | SignPresentationRequest | Signs a presentation. keyId | String | The Key index, public key or DID/Verification method key id | Default to null.

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 is related to the NFC card, can be stored on the NFC card. This method returns all stored Verifiable Credentials.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.files.getStoredCredentials().then(storedCredentialsResponse => {
  // handle credentials
}).catch(error => {
  // handle error
})

Return type

StoredCredentialsResponse

Getting a Verifiable Credential stored on the NFC Card

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

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.files.getStoredCredential(fileName).then(storedCredentialsResponse => {
  // handle credentials
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- fileName | String | The name of a credential | |

Return type

StoredCredentialsResponse

Deleting a 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 delete a specific stored Verifiable Credential.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.files.deleteStoredCredential(fileName).then(() => {
  // handle success
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- fileName | String | The file name of the credential |

Return type

None

Set Access Code

If an Access code is set on the card, all commands, including Scan Card, will require to submit this code. So if the Access code is lost, there is no way to recover the data or even retrieve the public key. Access codes may be enabled or disabled during card configuration at the factory. Also, it’s possible to prohibit removing the access code from the card once it’s set.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.wallet.setAccessCode(accessCode).then(successResponse => {
  // handle response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- accessCode | String | The access code |

Return type

SuccessResponse

Set Pass Code

Passcode protects signing and operations that can alter security parameters. The passcode may be enabled or disabled during card configuration at the factory. Also, it’s possible to prohibit removing the passcode from the card once it’s set.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.wallet.setPasscode(passcode).then(successResponse => {
  // handle response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- passcode | String | The pass code

Return type

SuccessResponse

Reset User Codes

Reset both access code and passcode if they were set.

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.wallet.resetUserCodes().then(successResponse => {
  // handle response
}).catch(error => {
  // handle error
})

Return type

SuccessResponse

Store Credential

Stores a credential a credential on the card

import NfcSdk from 'gimly-ssi-nfc-react-native';

NfcSdk.files.storeCredential(credential, fileName).then(successResponse => {
  // handle response
}).catch(error => {
  // handle error
})

Parameters

Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- credential | String |The data to be stored. fileName | String | The file name. fileCounter | Number | The file name.

Return type

SuccessResponse