BTCPayServer.NTag424.PCSC 1.0.11

BTCPayServer.BoltCardTools

Introduction

This repository hosts tools that help with the creation of Bolt Cards.

Content:

• BTCPayServer.NTag424 is the base library implementing the NTag424 protocol, this library is platform agnostic.
• BTCPayServer.NTag424.PCSC is a library implementing APDU transport via PCSC-Sharp for supporting Windows/Linux/Mac.

We tested the following smart card reader:

• identiv utrust 3700 f
• ACR122U-A9

Examples

How to read the UID of an NTag 424 smart card

Plug in a smart card reader, and place an NTag 424 smart card on it.

Reference the nuget package BTCPayServer.NTag424.PCSC in your project.

dotnet add package BTCPayServer.NTag424.PCSC

Then to use it:

using BTCPayServer.NTag424;
using BTCPayServer.NTag424.PCSC;
using System;

using var ctx = await PCSCContext.WaitForCard();
var ntag = ctx.CreateNTag424();
var key = AESKey.Default;
await ntag.AuthenticateEV2First(0, key);

var id = await ntag.GetCardUID();
var idStr = Convert.ToHexString(id, 0, id.Length).ToLowerInvariant();
Console.WriteLine($"Card UID: {idStr}");

How to read the NDEF message of an NTag 424 smart card

using BTCPayServer.NTag424.PCSC;
using System;

using var ctx = await PCSCContext.WaitForCard();
var ntag = ctx.CreateNTag424();
var uri = await ntag.TryReadNDefURI();
Console.WriteLine($"Card URI: {uri}");

How to verify the signature of an NTag 424 smart card

using BTCPayServer.NTag424;
using BTCPayServer.NTag424.PCSC;
using System;
using System.Security;
using System.Collections;

// Set keys have you have setup the card
var encryptionKey = AESKey.Default;
var authenticationKey = AESKey.Default;

using var ctx = await PCSCContext.WaitForCard();
var ntag = ctx.CreateNTag424();

var uri = await ntag.TryReadNDefURI();
var piccData = PICCData.TryBoltcardDecrypt(encryptionKey, authenticationKey, uri);
if (piccData == null)
    throw new SecurityException("Impossible to decrypt or validate");

// The LNUrlw service should also check `piccData.Counter` is always increasing between payments to avoid replay attacks.

How to setup a bolt card

using BTCPayServer.NTag424;
using BTCPayServer.NTag424.PCSC;
using System;
using System.Collections;

using var ctx = await PCSCContext.WaitForCard();
var ntag = ctx.CreateNTag424();

// Example with hard coded keys
var keys = new BoltcardKeys(
    AppMasterKey: new AESKey("00000000000000000000000000000001".HexToBytes()),
    EncryptionKey: new AESKey("00000000000000000000000000000002".HexToBytes()),
    AuthenticationKey: new AESKey("00000000000000000000000000000003".HexToBytes()),
    K3: new AESKey("00000000000000000000000000000004".HexToBytes()),
    K4: new AESKey("00000000000000000000000000000005".HexToBytes()));

var lnurlwService = "lnurlw://test.com";

// Note `BoltcardKeys.Default` assumes the card hasn't been setup yet.
// If it was not the case, you would need to provide the access keys you provided during the last setup.
await ntag.SetupBoltcard(lnurlwService, BoltcardKeys.Default, keys);

// You can reset the card to its factory state with `await ntag.ResetCard(keys);`

How to setup a bolt card with deterministic keys, and decrypt the PICCData

Deterministic keys simplifies the management of Boltcard by removing the need to store the keys of each Boltcards in a database.

Here is an example of how to setup a card with deterministic keys, and decrypt the PICCData.

using BTCPayServer.NTag424;
using BTCPayServer.NTag424.PCSC;
using System;
using System.Security;
using System.Collections;

using var ctx = await PCSCContext.WaitForCard();
var ntag = ctx.CreateNTag424();

await ntag.AuthenticateEV2First(0, AESKey.Default);
var uid = await ntag.GetCardUID();

var issuerKey = new AESKey("00000000000000000000000000000001".HexToBytes());
var batchKeys = new DeterministicBatchKeys(issuerKey, BatchId: 0);

var uri = await ntag.TryReadNDefURI();
var piccData = PICCData.TryDeterministicBoltcardDecrypt(batchKeys, uri, uid);
if (piccData == null)
    throw new SecurityException("Impossible to decrypt with batchKeys");
// If this method didn't throw an exception, it has been successfully decrypted and authenticated.

// You can reset the card with `await ntag.ResetCard(batchKeys);`.

License

MIT