Android 

Package details 

The package consists of a versioned zip file containing:

Shell
1Package/
2  SDK/
3    Android/
4      BChainSDK-release-X.aar
5      BChain - Sample - X

Package installation 

The SDK installation process consists of unzipping the package in a dedicated folder and copying the .aar file into the app libs folder.

Then update the application gradle file to add the SDK file references:

Kotlin
1implementation files("libs/BChainSDK-release-X.aar")

The SDK is now setup and ready to use.

SDK requirements 

Minimal API version: 23 (Android 6).

The SDK requires a keystore available on the phone with the algorithm “AES/CBC/NoPadding”. If this requirement is not matched, the SDK will not perform any actions on the card.

NFC settings 

The SDK use NFC to communicate with the card and a specific configuration is required to have the NFC working on the phone.

To setup the application, you have to add NFC permission for your application. To do this, add this line inside the manifest file in manifest level as mentioned below:

XML
1<!-- Android manifest setup -->
2<manifest ...>
3  <uses-permission android:name="android.permission.NFC" />
4</manifest>

Dependencies 

This SDK uses AndroidX compatibility library:

Kotlin
1implementation "androidx.appcompat:appcompat:1.3.0"

The SDK also uses the spongy castle library for cryptographic operations:

Kotlin
1implementation "com.madgag.spongycastle:core:1.58.0.0"
2implementation "com.madgag.spongycastle:prov:1.58.0.0"

Settings 

The SDK allows changing the AID used by the SDK by updating the string variable of SDKSettings.APPLET_AID

Kotlin
1SDKSettings.appletAid = "Custom AID value"

The default value is A0000000770306000A00000100020001.

SDK usage 

The Android SDK abstract the card communication and key functionalities, this SDK will use the NFC to communicate with the card, be sure that the application is ready and setup before continuing.

BChainManager 

BChainManager is the entry point of the library and contains all actions to perform on the card. This class requires an Android Context and an ICommunication object. To obtain an ICommunication object you have to use the class NFCHelper.

All methods are synchronous.

Usage sample:

Kotlin
1// BChainManager usage sample
2val context = ... // Get context
3val communication = ... // Get communication from NFCHelper
4val manager = BchainManager(context, communication) // Load manager
5manager.connect() // Connect to card
6manager.getCardStatus() // Execute actions ...

NFCHelper & ICommunication 

NFCHelper is a helper class that will handle the NFC functionalities and help to obtain an ICommunication object for the NFC (NFCCommunication), this class is required by the SDK manager to communicate with the card.

NFCHelper methods:

Usage sample:

Kotlin
1// NFCHelper usage sample
2// In activity
3override fun onResume() {
4  super.onResume ()
5  NFCHelper.getInstance().startCardDetector(this, this) // Start detector
6}
7
8override fun onPause() {
9  super.onPause()
10  NFCHelper.getInstance().stopCardDetector(this) // Stop card detector
11}
12
13override fun onCardDetected(communication: ICommunication) {
14  // card detected, use the communication parameter ...
15}

Methods details 

Find all method list and details here.

Custom keystore providers 

The SDK also provides a generic Java “Provider” interfaces to give access to card actions without directly using the SDK manager.

Here is what the custom “Provider” currently allows:

• Get public keys,
• Perform a signature,
• Initialize the card seed.

BChainProvider 

BChainProvider allows adding the classes BChainKeyStore and BChainSignature to the global provider, this step is required to use the others classes.

Code sample:

Kotlin
1BChainProvider.installProvider(App.context) // Install BChain providers

BChainKeyStore 

BChainKeyStore allows initializing the card seed and getting the card public keys. To obtain a class instance you need first to add it to the providers with BChainProvider, and then you can obtain the instance by calling the getInstance method with the parameter BChainKeyStore.KEY_INSTANCE.

Before using this instance, you need to pass some parameters with the method load with the class BChainKeyStoreParams as parameter. This class requires the Android NFC TAG object. That object can be obtained with the Android SDK methods (see android documentation for more details).

To perform a seed initialization you need to use the method setKeyEntry with the parameters:

• Alias: constant string to value seed – This indicate that we want to initialize the seed,
• Key: SecretKeySpec object with the seed as key and the algorithm can be empty,
• Chain: Not used, set it to null.

Initialize seed code sample:

Kotlin
1// Keystore initialize seed code sample
2val tag = ... // Get NFC TAG object
3val seed = Hex.decode("000102030405060708090a0b0c0d0e0f") // Seed in bytes
4BChainProvider.installProvider(App.context) // Install BChain providers
5val keystore = KeyStore.getInstance(BChainKeyStore.KEY_INSTANCE) // Load instance
6keystore.load(BChainKeyStoreParams(tag)) // Load params
7keystore.setKeyEntry("seed", SecretKeySpec(seed, ""), null, null) // Sets the seed to the cards

To get card’s public keys you need to use the method getKey with the parameters:

• Alias: string that represent a BIP32 path – This indicate the key we want to obtain,
• Password: Char array (4 chars) that represent the card PIN, this can be null or empty if we don’t want to use the PIN.

This method will by default return the public key in non-compressed format and without the chain code.

We can change the type of key we obtain by indicating with the BChainKeyStoreParams object parameter:

| Tag tag: Android NFC TAG,

| Boolean compressedKey: Indicate if we want compressed public key or not,

| Boolean withChainCode: Indicate if we want chain code included with public key or not.

Get public key code sample:

Kotlin
1// Keystore get public key sample
2val tag = ... // Get NFC TAG object
3val bipPath = "m/O'/O" // Crypto to use
4val pin = "1234"
5BChainProvider.installProvider(App.context) // Install BChain providers
6val keystore - KeyStore.getInstance(BChainKeyStore.KEY_INSTANCE) // Load instance
7keystore.load(BChainKeyStoreParams(tag, false, false)) // Load params
8val publicKey = keystore.getKey(bipPath, pin.toCharArray()) // Get public key

BChainSignature 

BChainSignature allows performing a signature with the card, to obtain a class instance you need first to add it to the providers with BChainProvider, and then you can obtain the instance by calling the getInstance method with the parameter BChainSignature.KEY_INSTANCE.

Before using this instance, you need to pass some parameters with the method initSign with the class BChainSignatureAuthKey as parameter, this class requires:

• Tag: The Android NFC TAG object, this object can be obtained with the Android SDK methods (see android documentation for more details),
• BipPath: String in BIP32 format that represent the key to use,
• Password: String that represent the card’s PIN can be empty or null if we do not want to use the Pin.

To perform a transaction signature, we first need to give the transaction-hashed data by calling the method update with the hash in parameters, and then call the method sign to obtain the signature.

The signature process returns the full raw response in DER format:

Signature code sample:

Kotlin
1// Custom signature code sample
2val tag = ... // Get NFC TAG object
3val bipPath = "m/O'/O" // Crypto to use val pin = "1234"
4val hash = ... // Build signature hash
5
6BChainProvider.installProvider(App.context) // Install BChain providers
7val signature = Signature.getInstance(BChainSignature.KEY_INSTANCE) // Load instance
8signature.initSign(BChainSignatureAuthKey(tag, bipPath, pin)) // Init params
9signature.update(hash) // Give data to sign
10val signatureData = signature.sign() // Perform signature