Problem

Some people use two (or more) readers. And each reader plays a specific role in their application. It is therefore important to identify each one.

While it is often possible to use the PC/SC reader name (see What is in a PC/SC reader name?), if you have two identical readers with no serial numbers, it becomes impossible to distinguish between them.

Solution

A USB device is connected to a USB bus with a specific topology. The lsusb --tree command, for example, can display the USB bus topology. The output looks like this:

$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 003: Dev 039, If 0, Class=Chip/SmartCard, Driver=usbfs, 12M

The smart card reader is connected to USB Port 003 on Bus 001. These numbers are fixed and linked to the computer's physical USB port. Disconnecting and reconnecting the reader to the same USB port will result in the same topology.

On GNU/Linux, the device number will change. For example, if I disconnect and reconnect the device, the reader's device number (Dev) will change from 039 to 040.

SCARD_CTL_CODE(3601)

This code is specific to my CCID driver. It comes after SCARD_CTL_CODE(3600) that is also specific/proprietary and used for MEP (see CCID driver and Multiple Enabled Profiles (MEP)).

Ideally, we would use a code defined by the PC/SC Workgroup but this group is essentially defunct and Microsoft is no longer a member. Microsoft stopped following the PC/SC Workgroup Specification a long time ago. Therefore, even if a name is defined by the PC/SC Workgroup, it will not be available on Windows.

API documentation

Use SCardControl() to send the control code SCARD_CTL_CODE(3601) to the reader. This code will be intercepted by the CCID driver. On return, you get a NUL-terminated string in the format <bus>-<port[.port[.port]]>:<config>.<interface> (e.g., 1-1.3.2:1.0) as found in /sys/bus/usb/devices/.

Source code

This example code is also included in the CCID driver's source code, in the examples/get_usb_path.py file.

The code also displays the SCARD_ATTR_CHANNEL_ID of the reader (see SCARD_ATTR_CHANNEL_ID and USB devices). This is an official PC/SC feature. It can be used when topology information is obtained from another source.

#! /usr/bin/env python3

"""
get_usb_path.py: get USB path of readers
Copyright (C) 2026  Ludovic Rousseau
"""

#   This program is free software; you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 3 of the License, or
#   (at your option) any later version.
#
#   This program is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License along
#   with this program; if not, see <http://www.gnu.org/licenses/>.

import struct
import smartcard
from smartcard.pcsc.PCSCPart10 import SCARD_CTL_CODE
from smartcard.scard import (
    SCARD_E_NOT_TRANSACTED,
    SCARD_E_INVALID_PARAMETER,
    SCARD_ATTR_CHANNEL_ID,
    SCARD_SHARE_DIRECT,
    SCARD_LEAVE_CARD,
)
from smartcard.util import toASCIIString


def get_usb_path(reader):
    """
    Display USB topology
    """
    print("Using:", reader)
    card_connection = reader.createConnection()
    card_connection.connect(mode=SCARD_SHARE_DIRECT, disposition=SCARD_LEAVE_CARD)

    # special control code
    ioctl_get_usb_path = SCARD_CTL_CODE(3601)
    try:
        res = card_connection.control(ioctl_get_usb_path)
    except smartcard.Exceptions.SmartcardException as ex:
        # SCARD_E_NOT_TRANSACTED returned by pcsc-lite
        # SCARD_E_INVALID_PARAMETER retruned by macOS
        if ex.hresult in [SCARD_E_NOT_TRANSACTED, SCARD_E_INVALID_PARAMETER]:
            print("Your driver does not (yet) support SCARD_CTL_CODE(3601)")
            return
        raise
    print("USB path:", toASCIIString(res))

    # get Channel ID
    attrib = card_connection.getAttrib(SCARD_ATTR_CHANNEL_ID)
    ddddcccc = struct.unpack("i", bytearray(attrib))[0]
    dddd = ddddcccc >> 16
    if dddd == 0x0020:
        bus = (ddddcccc & 0xFF00) >> 8
        addr = ddddcccc & 0xFF
        print(f" USB: bus: {bus}, addr: {addr}")
    print()


def main():
    """
    main
    """
    # for all the available readers
    for reader in smartcard.System.readers():
        get_usb_path(reader)


if __name__ == "__main__":
    main()

Output

$ ./get_usb_path.py
Using: Gemalto PC Twin Reader (70D7E2EE) 01 00
USB path: 1-3:1.0
 USB: bus: 1, addr: 39

$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 003: Dev 039, If 0, Class=Chip/SmartCard, Driver=usbfs, 12M

$ ./get_usb_path.py
Using: Gemalto PC Twin Reader (70D7E2EE) 01 00
USB path: 1-6:1.0
 USB: bus: 1, addr: 40

$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 006: Dev 040, If 0, Class=Chip/SmartCard, Driver=usbfs, 12M

$ ./get_usb_path.py
Using: Gemalto PC Twin Reader (70D7E2EE) 01 00
USB path: 1-3.1:1.0
 USB: bus: 1, addr: 42

$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 003: Dev 041, If 0, Class=Hub, Driver=hub/4p, 480M
        |__ Port 001: Dev 042, If 0, Class=Chip/SmartCard, Driver=usbfs, 12M

$ ./get_usb_path.py
Using: Gemalto PC Twin Reader (70D7E2EE) 01 00
USB path: 1-3.4:1.0
 USB: bus: 1, addr: 43

$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/16p, 480M
    |__ Port 003: Dev 041, If 0, Class=Hub, Driver=hub/4p, 480M
        |__ Port 004: Dev 043, If 0, Class=Chip/SmartCard, Driver=usbfs, 12M

Conclusion

Not everyone will need or use this feature. However, it can be very important if you have a large number of readers.

Many Thanks to Diego de los Santos for the idea and implementation.

Changes:

1.7.1 - 4 February 2026, Ludovic Rousseau

• Add support of

  • ACS APG8201-B2

  • BUDGET E-ID BUD001

  • CHERRY Smart Board 1150

  • CryptnoxCR CryptnoxCR

  • Diebold Nixdorf PN7362au CCID

  • FT BioPass FIDO2 Pro

  • Nitrokey Nitrokey Passkey

• Add SCARD_CTL_CODE(3601): USB path of the reader

• Some other minor improvements

pcsc-z

The wrapper is available at https://github.com/kofi-q/pcsc-z and is compatible for GNU/Linux, macOS and Windows.

The author is kofi-q.

The licence is MIT.

The API documentation can be found at https://kofi-q.github.io/pcsc-z/#pcsc.

Zig

From Wikipedia Zig article:

Zig is a system programming language designed to be a general-purpose improvement to the C programming language. It is free and open-source software, released under an MIT License.

Differences with C relate to control flow, function calls, library imports, variable declaration and Unicode support. The language makes no use of macros or preprocessor instructions. Features adopted from modern languages include the addition of compile time generic programming data types, allowing functions to work on a variety of data, along with a small set of new compiler directives to allow access to the information about those types using reflection. Zig requires manual memory management, but attempts to improve memory safety through option types and a unit testing framework. Features for low-level programming include packed structs, arbitrary-width integers and multiple pointer types.

Zig was designed by Andrew Kelly and first announced in 2016. Development is funded by the Zig Software Foundation (ZSF).

Installation

$ zig fetch --save=pcsc "git+https://github.com/kofi-q/pcsc-z.git"

I had to use an older version of the Zig-PC/SC wrapper because I used Zig 0.15.2 (stable version) instead of the development version 0.16.

$ zig fetch --save=pcsc "git+https://github.com/kofi-q/pcsc-z.git#zig-0.15"
info: resolved ref 'zig-0.15' to commit b347fd008c003ceb92041654a050c48d02468ce3
warning: overwriting existing dependency named 'pcsc'

Source code

To get started, you can use the zig init command to generate a minimal zig project.

$ zig init
info: created build.zig
info: created build.zig.zon
info: created src/main.zig
info: created src/root.zig
info: see `zig build --help` for a menu of options

You then need to update 2 files: src/main.zig and build.zig.

//! src/main.zig

const std = @import("std");
const pcsc = @import("pcsc");

pub fn main() !void {
    const client = try pcsc.Client.init(.SYSTEM);
    defer client.deinit() catch |err| std.debug.print(
        "Unable to release client: {t}",
        .{err},
    );

    // Connect to 1st reader
    var reader_names = try client.readerNames();
    if (reader_names.next()) |reader_name| {
        std.debug.print("Using: {s}\n", .{reader_name});

        // Connect to an inserted card:
        const card = try client.connect(reader_name, .SHARED, .ANY);
        defer card.disconnect(.LEAVE) catch |err| std.debug.print(
            "Unable to disconnect card: {t}\n",
            .{err},
        );

        std.debug.print("Card connected with protocol {f}\n", .{card.protocol});

        var buf_response: [pcsc.max_buffer_len]u8 = undefined;

        // SELECT command
        const select = [_]u8{ 0x00, 0xA4, 0x04, 0x00, 0x0A, 0xA0, 0x00,
            0x00, 0x00, 0x62, 0x03, 0x01, 0x0C, 0x06, 0x01 };

        std.debug.print("Transmitting APDU: {x}\n", .{select});

        var response = try card.transmit(&select, &buf_response);
        std.debug.print("Received response: {x}\n", .{response});

        // TEST command
        const command = [_]u8{ 0x00, 0x00, 0x00, 0x00 };

        std.debug.print("Transmitting APDU: {x}\n", .{command});

        response = try card.transmit(&command, &buf_response);
        std.debug.print("Received response: {x}\n", .{response});

        // Truncate the 2 last bytes: status word
        const text = response[0..response.len-2];
        std.debug.print("Text: {s}\n", .{text});
    } else {
        std.debug.print("No reader found\n", .{});
    }
}

//! build.zig

const std = @import("std");

pub fn build(b: *std.Build) !void {
    const target = b.standardTargetOptions(.{});
    const mode = b.standardOptimizeOption(.{});

    const pcsc_dep = b.dependency("pcsc", .{
        .optimize = mode,
        .target = target,
    });

    const pcsc_mod = pcsc_dep.module("pcsc");

    const exe = b.addExecutable(.{
        .name = "pcsc-demo",
        .root_module = b.createModule(.{
            .imports = &.{
                .{ .name = "pcsc", .module = pcsc_mod },
            },
            .optimize = mode,
            .root_source_file = b.path("src/main.zig"),
            .target = target,
        }),
    });

    const demo_run = b.addRunArtifact(exe);
    const demo_step = b.step("demo", "Run PCSC demo");
    demo_step.dependOn(&demo_run.step);
}

Output

$ zig build demo
Using: Gemalto USB SmartCard Reader
Card connected with protocol T=1
Transmitting APDU: 00a404000aa00000006203010c0601
Received response: 9000
Transmitting APDU: 00000000
Received response: 48656c6c6f20776f726c64219000
Text: Hello world!

Conclusion

Zig is a relatively new programming language. We can already find a PC/SC wrapper for it. That is great!

If you are working on a Free Software PC/SC wrapper that is not yet on my list please let me know.

Protocol negotiation

To ensure that the client and server are using the same protocol, they negotiate the procotol they know. If they are different, the server will refuse the connection. In the application (client side), the SCardEstablishContext() function will return the error code SCARD_E_SERVICE_STOPPED.

Up to version 2.4.0, both the server and the client only supported one protocol version (version 4:5).

Sandboxes

Flatpack, Snap, AppImage and other sandbox technologies are now used to distribute applications.

In some/many cases, the server (pcscd daemon) running on the host comes from a different version of pcsc-lite than the client used in the sandbox. If the internal communication protocol differs, the communication is not possible.

I receive requests to solve this problem. See:

• Backward protocol compatibility #199

• Runtime-configurable IPC dir #246

• Support multiple versions of the internal protocol: fix Flatpak issues

Protocol History

New protocol negotiation

From pcsc-lite 2.4.1 onwards, the protocol negotiation is smarter.

The daemon side will accept the current version and also the previous one. Versions 4:5 and 4:4 are accepted. It is straightforward, as the only change with version 4:5 is the addition of a new command (command CMD_GET_READER_EVENTS introduced in commit 53f57ed700bcd0bc47d970dc674ba3fd5ee5b387). Old clients will simply not use the new command.

The client side will also accept the current version and the previous one. These are versions 4:5 and 4:4. Using a recent client (protocol 4:5) with an old server (protocol 4:4) will have a small side effect. The SCardGetStatusChange() function will not include the number of reader events (see Improved SCardGetStatusChange() for "\\?PnP?\Notification" special reader).

Applications using pcsc-lite 2.4.1 can use a daemon as old as pcsc-lite version 1.8.24, released in October 2018.

A pcscd daemon from pcsc-lite 2.4.1 can handle clients as old as the same pcsc-lite version 1.8.24 from October 2018.

Supporting the (older) protocol version 4:3 may be possible but would require more efforts and be more complex. Contact me if you require this.

Conclusion

This change should help mix PC/SC servers and clients from more different versions.

This should prevent people from using ugly hacks.

Changes:

2.4.1: Ludovic Rousseau

1 January 2026

• Add backward version support on the client side

• Add backward version support on the server side

• hotplug libudev: rescan the USB bus with pcscd --hotplug

• fix a value in pcscd.service systemd file

• meson: install systemd files even if libsystemd is not used

• Some other minor improvements

Statistics

In 2025 the blog served 355,108 pages (+57%) totalling 35.89 GB (+35%). I would say that a large part of the increase in traffic is due to artificial intelligence bots scraping the website.

Conclusion

Last year, I asked people to contact me with suggestions for new subjects or tools. However, I received nothing.

This blog does not contain any advertising. If you would like to support me you can become a GitHub Sponsors.

Problem

I wanted to use ssh-agent with a PKCS#11 library on macOS. So I tried adding the smart card using the command ssh-add -s but I received the following error:

 $ ssh-add -s /Library/Frameworks/xyz.framework/Versions/A/libxyz.dylib
 Enter passphrase for PKCS#11:
 Could not add card "/Library/Frameworks/xyz.framework/Versions/A/libxyz.dylib": agent refused operation

The error agent refused operation is not very informative. From the logs of the PKCS#11 library, I can see that the library is not being used at all. The problem does not come from the library, which would have returned an error.

Analysis

In order to analyse the problem, I tried debugging the version of OpenSSH provided by Apple. However, I encountered another issue. See my previous article Apple and OpenSSH modified source code.

To find out exactly what is happening, we need to obtain the logs from ssh-agent command, rather than the ssh-add command. So I restart ssh-agent in debug mode and I re-run the ssh-add command.

 $ ssh-agent -d
 [...]
 debug1: new_socket: type = CONNECTION
 debug2: fd 4 setting O_NONBLOCK
 debug1: process_message: socket 1 (fd=4) type 20
 debug2: process_add_smartcard_key: entering
 refusing PKCS#11 add of "/Library/Frameworks/xyz.framework/Versions/A/libxyz.dylib": provider not allowed

The error here is different: provider not allowed.

The ssh-agent manpage indicates an option [-P allowed_providers].

-P allowed_providers
        Specify  a pattern-list of acceptable paths for PKCS#11 provider
        and FIDO authenticator middleware shared libraries that  may  be
        used with the -S or -s options to ssh-add(1).  Libraries that do
        not match the pattern list will be refused.  The default list is
        "/usr/lib*/*,/usr/local/lib*/*".

The problem is clear. The PKCS#11 library is located in /Library/Frameworks/, which is not included in the default list of allowed directories.

Solutions

Update the way ssh-agent is started by adding the -P '/Library/Frameworks/*' option.

Alternatively, copy or install the PKCS#11 library somewhere in the /usr/local/lib/ directory.

Conclusion

I wrote this blog article to ensure that it is indexed by web search engines, so that other people can find it when searching for the ssh-add error agent refused operation message.

Using Free Software is really helpful when you need to debug an issue. You can read (and modify) the source code to identify the problem.

I should sometimes read a program's manpage before looking at its source code 😀.

Source code

The source code is available in the github repository: apple-oss-distributions/OpenSSH.

Very well. An Xcode project is also inlcuded. It should be a breeze to rebuild the command I need and debug it.

Rebuild

When compiling, I get the following error:

error: unable to find sdk 'macosx.internal' (in target 'ssh' from project 'OpenSSH')

This is because the configured SDK (SDKROOT) is set to macosx.internal. See https://github.com/apple-oss-distributions/OpenSSH/blob/OpenSSH-354.0.3/xcconfigs/base.xcconfig#L9.

//  Copyright © 2023 Apple Inc. All rights reserved.
//
//  NOTE: We use MixedCase for user-defined settings.

PRODUCT_NAME = $(TARGET_NAME)
PRODUCT_MODULE_NAME = $(TARGET_NAME:identifier)
PRODUCT_BUNDLE_IDENTIFIER = com.apple.$(TARGET_NAME:rfc1034identifier)

SDKROOT = macosx.internal
MACOSX_DEPLOYMENT_TARGET = 14.0
[...]

Of course I don't have this internal SDK.

OK. I can try using the default SDK (while searching for "macosx.internal", I found a tool that does just that: fix-macos-internal-sdk). But now I get the following error:

.../OpenSSH/sshd-keygen-wrapper/SystemProperties.swift:3:8: error: Unable to find module dependency: 'DarwinPrivate'
import DarwinPrivate.os.variant
           ^ (in target 'sshd-keygen-wrapper' from project 'OpenSSH')
.../OpenSSH/sshd-keygen-wrapper/SystemProperties.swift:3:8: note: A dependency of main module 'sshd_keygen_wrapper'
import DarwinPrivate.os.variant
           ^ (in target 'sshd-keygen-wrapper' from project 'OpenSSH')

Unsurprisingly, some dependencies are now missing. DarwinPrivate is required.

Of course, I don't have the DarwinPrivate package used here https://github.com/apple-oss-distributions/OpenSSH/blob/OpenSSH-354.0.3/sshd-keygen-wrapper/SystemProperties.swift#L3.

import IOKit
import System
import DarwinPrivate.os.variant

protocol SystemPropertiesStrategy {
[...]

Other packages are also required and missing:

• AppleKeyStore https://github.com/apple-oss-distributions/OpenSSH/blob/OpenSSH-354.0.3/sshd-keygen-wrapper/SSHDWrapper.swift#L1

• CoreAnalytics https://github.com/apple-oss-distributions/OpenSSH/blob/OpenSSH-354.0.3/sshd-keygen-wrapper/SSHDWrapper.swift#L2C8-L2C21

import AppleKeyStore
import CoreAnalytics
import Foundation
import System

struct SSHDWrapper {
[...]

Another option

Rebuilding OpenSSH as provided by Apple is not working. However, it is possible is to try rebuilding OpenSSH from its upstream source code i.e. OpenSSH Portable Release.

This is what I did. I managed to compile OpenSSH Portable (very easily) and debug my problem (we'll come back to that later).

Conclusion

The source code of the modified OpenSSH is provided by Apple. But you cannot recompile it without components that are internal (to my knowledge) to Apple and, of course, not provided by Apple.

This may be the difference between Open Source and Free Software.

Unmaintained drivers

Some older, unmaintained drivers will no longer work with pcscd. I have requested their removal from Debian unstable.

They are:

• libasedrive-serial & libasedrive-usb from asedriveiiie (see bug #1119077)

• libgempc410 & libgempc430 from ifd-gempc (see bug #1119078)

I am the Debian maintainer of these packages, so it is my responsibility to open tickets to remove the packages.

I also filed a release critical bug #1119081 on libgcr410 so that this driver will not be included in the next version of Debian (unless the issue is fixed).

Popularity

I have already published an article on the popularity of Debian packages for smart cards in 2020 in Smart card Usage in Debian: pcscd and drivers.

With updated graphics, we now have:

• asedriveiiie

• ifd-gempc

• libgcr410

Very few people still have these packages installed. And even fewer use them.

Changes required

I also filed the bug #39 "Set group to pcscd in the udev rules file" on the upstream acsccid driver.

This driver is a fork of my CCID driver and is still actively maintained. The problem should therefore be resolved in a new version.

Conclusion

I don't have enough free time to maintain software that is no longer in use.

I haven't used these drivers for at least 10 years. And I don't plan on using them in the future, because I discovered that I no longer have the smart card readers.

Changes:

2.3.1 (October 2025)

• Add support of SWIG 4.4.0

• Add support of Mac OS X Snow Leopard

• Minor changes