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