BTCPayServer.NTag424 1.0.23

dotnet add package BTCPayServer.NTag424 --version 1.0.23                
NuGet\Install-Package BTCPayServer.NTag424 -Version 1.0.23                
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" Version="1.0.23" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BTCPayServer.NTag424 --version 1.0.23                
#r "nuget: BTCPayServer.NTag424, 1.0.23"                
#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 as a Cake Addin
#addin nuget:?package=BTCPayServer.NTag424&version=1.0.23

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

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 (1)

Showing the top 1 NuGet packages that depend on BTCPayServer.NTag424:

Package Downloads
BTCPayServer.NTag424.PCSC

A library to communicate with NTag 424 chips and assist BoltCard creation

GitHub repositories (1)

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

Repository Stars
btcpayserver/btcpayserver
Accept Bitcoin payments. Free, open-source & self-hosted, Bitcoin payment processor.
Version Downloads Last updated
1.0.23 2,844 4/24/2024
1.0.22 3,311 2/8/2024
1.0.21 120 1/25/2024
1.0.20 1,420 12/21/2023
1.0.19 861 12/21/2023
1.0.18 658 12/8/2023
1.0.17 235 11/3/2023
1.0.16 174 10/25/2023
1.0.15 134 10/24/2023
1.0.14 110 10/24/2023
1.0.13 124 10/24/2023
1.0.12 115 10/24/2023
1.0.11 187 10/23/2023
1.0.10 138 10/22/2023
1.0.9 130 10/22/2023
1.0.8 117 10/21/2023
1.0.7 108 10/20/2023
1.0.6 115 10/20/2023
1.0.5 123 10/20/2023
1.0.4 123 10/20/2023
1.0.3 124 10/20/2023
1.0.2 104 10/20/2023
1.0.1 119 10/6/2023
1.0.0 102 10/4/2023