BTCPayServer.NTag424.PCSC 1.0.21

dotnet add package BTCPayServer.NTag424.PCSC --version 1.0.21                
NuGet\Install-Package BTCPayServer.NTag424.PCSC -Version 1.0.21                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BTCPayServer.NTag424.PCSC" Version="1.0.21" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BTCPayServer.NTag424.PCSC --version 1.0.21                
#r "nuget: BTCPayServer.NTag424.PCSC, 1.0.21"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BTCPayServer.NTag424.PCSC as a Cake Addin
#addin nuget:?package=BTCPayServer.NTag424.PCSC&version=1.0.21

// Install BTCPayServer.NTag424.PCSC as a Cake Tool
#tool nuget:?package=BTCPayServer.NTag424.PCSC&version=1.0.21                

BTCPayServer.BoltCardTools

Introduction

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

Content:

We tested the following smart card reader:

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.TryBoltcardDecryptCheck(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 System.Security;
using BTCPayServer.NTag424;

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

// In prod: var issuerKey = IssuerKey.Random();
var issuerKey = new IssuerKey(new byte[16]);

// First time authenticate is with the default 00.000 key
await ntag.AuthenticateEV2First(0, AESKey.Default);
var uid = await ntag.GetCardUID();
var cardKey = issuerKey.CreateCardKey(uid, 0);
// RegisterCard should be implemented by the server
await RegisterCard(issuerKey.GetId(uid), cardKey.Version);

var keys = cardKey.DeriveBoltcardKeys(issuerKey);
await ntag.SetupBoltcard("lnurlw://blahblah.com", BoltcardKeys.Default, keys);

var uri = await ntag.TryReadNDefURI();
var piccData = issuerKey.TryDecrypt(uri);
if (piccData == null)
    throw new SecurityException("Impossible to decrypt with issuerKey");


// In production, you would fetch the card key from database
// var registration = await GetRegistration(issuerKey.GetId(piccData.Uid));
// if (registration.State == "Reset") throw new SecurityException("Card reset state");
// cardKey = issuerKey.CreateCardKey(uid, registration.Version);

if (!cardKey.CheckSunMac(uri, piccData))
    throw new SecurityException("Impossible to check the SUN MAC");

// If this method didn't throw an exception, it has been successfully decrypted and authenticated.
// You can reset the card with `await ntag.ResetCard(issuerKey, cardKey);`.

License

MIT

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on BTCPayServer.NTag424.PCSC:

Repository Stars
btcpayserver/BTCPayServer.Vault
Sign with software or hardware wallets
Version Downloads Last updated
1.0.21 91 9/4/2024
1.0.20 131 4/24/2024
1.0.19 136 2/8/2024
1.0.18 408 12/21/2023
1.0.17 120 12/21/2023
1.0.16 225 12/8/2023
1.0.15 227 10/25/2023
1.0.14 152 10/24/2023
1.0.13 153 10/24/2023
1.0.12 145 10/24/2023
1.0.11 211 10/23/2023
1.0.10 160 10/22/2023
1.0.9 145 10/22/2023
1.0.8 157 10/21/2023
1.0.7 131 10/20/2023
1.0.6 135 10/20/2023
1.0.5 149 10/20/2023
1.0.4 144 10/20/2023
1.0.3 139 10/20/2023
1.0.1 149 10/6/2023
1.0.0 125 10/4/2023