OpenPGP卡工具

本库包含用于检查、配置和使用OpenPGP卡的oct工具。

安装

通过"cargo"工具安装此库是一种简单的方法。

要在当前Fedora上构建，需要以下构建依赖项

# dnf install rustc cargo pcsc-lite-devel

对于当前的Debian，需要一个足够新的Rust工具链（rustc和cargo）（Debian稳定版中的版本可能过旧），另外

# apt install pkg-config libpcsclite-dev

之后，您可以通过运行以下命令来安装此库

$ cargo install openpgp-card-tools --locked

最后，将$HOME/.cargo/bin添加到您的PATH中，以便运行已安装的二进制文件。

系统集成

oct使用PC/SC框架。因此，在基于Linux的系统上，您需要确保pcscd服务正在运行，以便能够访问您的OpenPGP卡。

手册页

要为oct生成手册页，请通过OCT_MANPAGE_OUTPUT_DIR环境变量提供一个绝对目录。在创建指定目录下的手册页后，应用程序退出。

$ OCT_MANPAGE_OUTPUT_DIR=/some/directory oct

Shell补全

要为oct生成shell补全，请通过OCT_COMPLETION_OUTPUT_DIR环境变量提供一个绝对目录。在创建指定目录下的shell补全后，应用程序退出。

$ OCT_COMPLETION_OUTPUT_DIR=/some/directory oct

oct

一个用于检查、配置和使用OpenPGP卡的工具。

此工具旨在便于常规交互式使用以及从脚本中使用。为此，此工具的所有功能都可以以非交互式方式使用（见下文）。

在交互式环境中使用工具时，支持两种PIN输入方法：在大多数情况下，PIN可以通过宿主计算机输入（并且必须如此）。当智能卡读卡器上可用PIN键盘时，将通过此PIN键盘请求PIN输入。

列出卡片

列出所有已连接卡片的标识符

$ oct list
Available OpenPGP cards:
 ABCD:01234567
 0007:87654321

检查卡片状态

打印有关卡片上数据的状态信息。如果只有一个卡片连接，则卡片是隐式选择的。

$ oct status
OpenPGP card ABCD:01234567 (card version 3.4)

Cardholder: Alice Adams
Language preferences: 'en'

Signature key
  Fingerprint: 034b348ceda2064caa2274e47563e86f5cabc2a4
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: EdDSA (Ed25519)
  Signatures made: 11

Decryption key
  Fingerprint: 338bee093950d831a76f0eb913d62df68c9e5176
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: ECDH (Curve25519)

Authentication key
  Fingerprint: 4881a22e7ec626d1120250b0a7d7f0d50c8df719
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: EdDSA (Ed25519)

Remaining PIN attempts: User: 3, Admin: 3, Reset Code: 0

显式打印特定卡的状信息（当插入多个卡时，需要此命令语法）

$ oct status --card ABCD:01234567

添加 -v 以获取更详细的卡状态

OpenPGP card ABCD:01234567 (card version 3.4)

Cardholder: Alice Adams
Language preferences: 'en'

Signature key
  Fingerprint: 034b348ceda2064caa2274e47563e86f5cabc2a4
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: EdDSA (Ed25519)
  Touch policy: Cached (features: Button)
  Key Status: generated
  User PIN presentation is valid for unlimited signatures
  Signatures made: 11

Decryption key
  Fingerprint: 338bee093950d831a76f0eb913d62df68c9e5176
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: ECDH (Curve25519)
  Touch policy: Off (features: Button)
  Key Status: generated

Authentication key
  Fingerprint: 4881a22e7ec626d1120250b0a7d7f0d50c8df719
  Creation Time: 2022-05-21 13:15:19 UTC
  Algorithm: EdDSA (Ed25519)
  Touch policy: Off (features: Button)
  Key Status: generated

Attestation key:
  Algorithm: RSA 2048 [e 17]
  Touch policy: Cached (features: Button)

Remaining PIN attempts: User: 3, Admin: 3, Reset Code: 0
Key Status (#129): imported

--public-key-material 标志会额外输出每个密钥槽的原始公钥数据。

从卡中获取 OpenPGP 公钥表示

此命令返回卡上密钥的 OpenPGP 公钥表示。

要将解密和身份验证子密钥（如果有）绑定到签名密钥，需要提供用户PIN。

$ oct pubkey
OpenPGP card ABCD:01234567
Enter User PIN:
-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: F9C7 97CB 1AF2 1C68 AEEC  8D4D 1002 89F5 5EF6 B2D4
Comment: Alice Adams

xjMEYkOmahYJKwYBBAHaRw8BAQdADwHIuuSgboyzgcLci8Hc0Q15YHKfDP8/CZG4
uumYosXNA2JhesLABgQTFgoAeAWCYkjTagWJAAAAAAkQEAKJ9V72stRHFAAAAAAA
HgAgc2FsdEBub3RhdGlvbnMuc2VxdW9pYS1wZ3Aub3JnifpLw5yhNlKffk7V+P9g
idnIM3j6l3k34+p7tMQmCPoCmwMWIQT5x5fLGvIcaK7sjU0QAon1Xvay1AAAhJkB
AIEhZTDuc9xARVK8ta51SOpX3mZs/UYA5a+UrB6vpmZ3AP4k14gFQ6q/cl/SOhPR
FpCAvYlqL8rb3gc2sFIZDfYUDM4zBGJDpmoWCSsGAQQB2kcPAQEHQDRodITykZoi
hIIPZcFZ2bMXvo20YEv+I1eg2kFQ2qSqwsAGBBgWCgB4BYJiSNNqBYkAAAAACRAQ
Aon1Xvay1EcUAAAAAAAeACBzYWx0QG5vdGF0aW9ucy5zZXF1b2lhLXBncC5vcmcI
5rVHhWA5cGdYlyQJYRXv4osAyFlyznFiUOATnoT6LgKbIBYhBPnHl8sa8hxoruyN
TRACifVe9rLUAADpTwD/a+AlBGryfLsqFzIhdJRpGkoOl0H+xcgk3vcaPUQq0pcA
/3TtUmaJ5w60qb/Px7/Q+MTymHH54elRY4lvwIfbvkUIzjgEYkOmahIKKwYBBAGX
VQEFAQEHQO5KBZ7cMwwjsXGOWWMqgAkCyNdw7smcx/+jBEk0m38dAwEKCcLABgQY
FgoAeAWCYkjTagWJAAAAAAkQEAKJ9V72stRHFAAAAAAAHgAgc2FsdEBub3RhdGlv
bnMuc2VxdW9pYS1wZ3Aub3Jn9IwQkbcw9W0jfrduv1q4qNhsOgJWkGTMbVyvQCug
YpcCmwwWIQT5x5fLGvIcaK7sjU0QAon1Xvay1AAAfTwBAPSQq/hGcGjAWNePHoLH
5zA/ePu1vaY1nh2dPhqtUg8+AP0TDG96MJxlM8SJUQXtQsJCAEo4qT9GnGi7MyTU
nvraDw==
=es4l
-----END PGP PUBLIC KEY BLOCK-----

可以查询特定卡

$ oct pubkey --card ABCD:01234567

在将卡上的密钥材料（公钥）导出为证书的过程中，可以将一个或多个用户ID绑定到证书上

$ oct pubkey --userid "Alice Adams <[email protected]>"

注意：导出的公钥材料并不总是你想要的

从卡中导出公钥材料的结果只是原始公钥的一个近似，因为OpenPGP卡上没有一些元数据。这些缺失的元数据包括过期日期。

此外，如果你的卡只包含子密钥，但没有原始主密钥，那么导出的证书将使用卡上的签名子密钥作为导出证书的主密钥。

处理从卡中导出的公钥材料的一种安全方法是使用 sq key adopt。

当你可以访问你的私有主密钥材料时，可以使用这种方法（在以下示例中，我们假设此密钥存储在 key.pgp 中）。然后，你可以将卡上的公钥材料绑定到你的密钥

oct pubkey > public.key
sq key adopt key.pgp public.pgp

在此过程中，您可以手动设置任何相关标志。

使用卡进行 ssh 认证

要使用 OpenPGP 卡进行 ssh 登录认证，必须在卡上存在 PGP 认证密钥。

oct ssh 会显示卡上 PGP 认证密钥的 ssh 公钥字符串表示，如下所示

$ oct ssh
OpenPGP card ABCD:01234567

Authentication key fingerprint:
59a5cd3ea88f8707d887eaae13545f404e11be1c

SSH public key:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII2dcYBqMCamidT5MpE3Cl3MIKcYMBekGXbK2aaN6JaH oct:ABCD:01234567

要将远程机器的登录权限允许，可以将该 ssh 公钥添加到该远程机器上的 .ssh/authorized_keys

在上面的示例输出中，此字符串是 ssh 公钥

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII2dcYBqMCamidT5MpE3Cl3MIKcYMBekGXbK2aaN6JaH oct:ABCD:01234567

显示 OpenPGP 卡元数据

打印有关卡的功能的信息，包括支持的算法列表（如果卡返回此列表）。

大多数输出可能对普通用户没有兴趣。

$ oct info
OpenPGP card FFFE:12345678 (card version 2.0)

Application Identifier: D276000124 01 0200 FFFE 12345678 0000
Manufacturer [FFFE]: Range reserved for randomly assigned serial numbers.

Card Capabilities:
- command chaining

Card service data:
- Application Selection by full DF name
- EF.DIR and EF.ATR/INFO access services by the GET DATA command (BER-TLV): 010

Extended Capabilities:
- get challenge
- key import
- PW Status changeable
- algorithm attributes changeable
- KDF-DO
- maximum length of challenge: 32
- maximum length cardholder certificates: 2048
- maximum command length: 255
- maximum response length: 256

Supported algorithms:
- SIG: RSA 2048 [e 32]
- SIG: RSA 4096 [e 32]
- SIG: ECDSA (Secp256k1)
- SIG: EdDSA (Ed25519)
- SIG: EdDSA (Ed448)
- DEC: RSA 2048 [e 32]
- DEC: RSA 4096 [e 32]
- DEC: ECDSA (Secp256k1)
- DEC: ECDH (Curve25519)
- DEC: ECDH (X448)
- AUT: RSA 2048 [e 32]
- AUT: RSA 4096 [e 32]
- AUT: ECDSA (Secp256k1)
- AUT: EdDSA (Ed25519)
- AUT: EdDSA (Ed448)

或查询特定卡

$ oct info --card ABCD:01234567

管理命令

所有 admin 命令都需要管理 PIN。它可以作为一个文件提供，使用 -P <admin-pin-file>，用于非交互式使用（见下文）。

默认情况下，PIN 必须在主机计算机上交互式输入，或者如果 OpenPGP 卡在带有 PIN 按钮的智能卡读卡器中使用，则通过 PIN 按钮输入。

设置触摸策略

卡可能需要在执行加密操作之前由用户确认（此确认功能通常在卡上作为机械按钮实现）。

但是，并非所有卡都实现了此功能。

理由：当卡需要触摸确认时，即使攻击者控制了用户的宿主机，也无法随意在卡上执行加密操作——即使他们知道了用户的 PIN。

此功能是按密钥槽配置的。用户可以选择分别对于签名、解密、身份验证和证明操作要求（或不要求）触摸确认。

例如，当将触摸策略设置为 On 时，对于 SIG 密钥槽，则每个签名操作都需要触摸按钮确认

$ oct admin --card ABCD:01234567 touch --key SIG --policy On

密钥槽的有效值包括：SIG、DEC、AUT、ATT（某些卡只支持前三个）。

可用的策略包括：Off、On、Fixed、Cached、CachedFixed。某些卡只支持这些策略的子集。

• Off表示不需要触摸确认。
• On表示每次操作都需要触摸确认。
• Fixed策略类似于On，但无法更改策略，除非在卡上执行出厂重置。
• 使用Cached策略时，触摸确认在15秒内对多次操作有效。

设置持卡人姓名

设置（信息性）持卡人姓名

$ oct admin --card ABCD:01234567 name "Alice Adams"

设置证书URL

OpenPGP卡的URL字段旨在指向与卡上存在的密钥相对应的证书（或“公钥”）。

它可以设置为以下格式

$ oct admin --card ABCD:01234567 url "https://key.url.example"

使用keys.openpgp.org作为URL

如果您已上传（或计划上传）您的证书（您的公钥）到keys.openpgp.org密钥服务器，您可以将卡的URL字段指向那里

如果您的证书指纹为0123456789ABCDEF0123456789ABCDEF01234567，则可以按以下方式设置URL

$ oct admin --card FFFE:12345678 url "https://keys.openpgp.org/vks/v1/by-fingerprint/0123456789ABCDEF0123456789ABCDEF01234567"

证书URL的常见选项

您可以使用任何提供您的证书（“公钥”）的URL，包括指向

• gitlab（https://gitlab.com/<username>.gpg）或github（https://github.com/<username>.gpg）的链接
• 其他任何密钥服务器，例如https://keyserver.ubuntu.com/，
• 一个WKD服务器，
• 您的个人网站上的证书副本...

导入密钥

将私钥导入卡。如果每个角色（签名、解密、认证）在key.priv中最多有一个（子）密钥，则此功能有效。

$ oct admin --card ABCD:01234567 import key.priv

在明确选择子密钥的同时将私钥导入卡。如果key.priv中任何角色存在多个子密钥，则需要明确指定指纹。指纹中的空格将被忽略。

$ oct admin --card ABCD:01234567 -P <admin-pin-file> import key.priv \
 --sig-fp f290dbbf21db86343c96157b87be15b7f548d97c \
 --dec-fp 3c6e08f6761389358b8d766673c7f1a9eedac360 \
 --auth-fp d6aa48ef39a26f26c42d5bcbaad214d55332c838

当只为角色的子集指定指纹时，不会为其他角色导入密钥。

密码保护的私钥材料

如果导入文件中的私钥（子）键使用密码锁定，则用户将被提示输入密码。如果（子）密钥使用不同的密码加密，则用户将被多次提示。

（背景：OpenPGP密钥在文件中存储时可以设置密码保护。但是，为了导入到OpenPGP卡，必须以未加密的形式提供密钥。因此，它们需要解密才能导入。）

对于非交互式工作流程，可以从文件中提供密码。

$ oct admin --card ABCD:01234567 import --key-passphrase passphrase.txt key.priv

请注意，密码文件的正文被原样使用，包括例如任何尾随空格或换行符。生成不带尾随换行符的密码文件的一种方法是

$ echo -n "my passphrase" > passphrase.txt

（请注意，执行此类命令可能会将您的密码存储在shell历史文件中。如果需要，请采取措施避免这种情况。）

在卡上生成密钥

此命令在OpenPGP卡上生成新密钥。它在一个输出文件中创建相应的证书（“公钥”）表示形式。

$ oct admin --card ABCD:01234567 generate --output <output-cert-file> curve25519

请注意，密钥生成需要管理员PIN和用户PIN（用户PIN用于将新密钥导出为公钥）。

生成的密钥的加密算法可以选择作为（可选的）最后一个参数。在我们的例子中，我们使用 curve25519，通常如果您的卡支持的话，这也是您想要的。根据您所使用的特定卡的特性，以下算法名称可能受到支持： curve25519、rsa2048、rsa3072、rsa4096、nistp256、nistp384、nistp521（在现代卡上，oct info 命令会显示特定设备支持的算法表）。

输出将如下所示

Enter Admin PIN:
Enter User PIN:
 Generate subkey for Signing
 Generate subkey for Decryption
 Generate subkey for Authentication

<output-cert-file> 将包含相应的证书（“公钥”）。

在卡上生成密钥材料的过程中，必须包含一个或多个用户ID与导出的证书一起使用

$ oct admin --card ABCD:01234567 generate --userid "Alice Adams <[email protected]>" --output <output-cert-file> curve25519

签名

此工具支持创建 三种不同形式的 OpenPGP 签名：分离签名、内联签名和明文签名。

如果没有提供输入文件，则读取 stdin。默认情况下，输出发送到 stdout，但可以使用命令行选项将其重定向到文件。

分离

$ oct sign --card ABCD:01234567 detached <input-file>

内联

$ oct sign --card ABCD:01234567 inline <input-file>

明文

$ oct sign --card ABCD:01234567 cleartext <input-file>

解密

使用卡解密（如果没有设置输入文件，则读取 stdin）

$ oct decrypt --card ABCD:01234567 <input-file>

PIN 管理

OpenPGP 卡使用 PIN（数字密码）来验证用户是否有权执行操作。

要在卡上使用加密操作（如解密或签名），需要 用户 PIN。

要配置卡（例如将 OpenPGP 密钥材料导入卡的密钥槽），需要 管理员 PIN。

默认情况下，在未配置（或出厂重置）的卡上，用户 PIN 通常设置为 123456，管理员 PIN 设置为 12345678。

已阻止的卡和重置

当用户多次输入错误的用户 PIN 时，卡将进入已阻止状态，在这种状态下，成功提供用户 PIN 是不可能的。这样做的目的是为了防止攻击者尝试所有可能的 PIN（例如，在盗取卡后）。

要再次使用卡，必须“重置”用户 PIN。

用户 PIN 重置可以通过提供管理员 PIN 来执行。

重置代码

OpenPGP 卡提供了一个额外的、可选的 重置代码 机制。

重置代码可以在卡上配置并用于在忘记或阻止用户 PIN 时重置用户 PIN。在用重置代码解锁卡时，不需要管理员 PIN。

重置代码机制仅在用户无法访问（或不想使用）管理员 PIN 的场景中才有用（例如，在某些企业设置中，用户可能不会获得卡的管理员 PIN。相反，管理员可以定义一个重置代码并将该代码提供给用户）。

在未配置（或出厂重置）的卡上，重置代码通常未设置。

设置新的用户 PIN

设置新的用户 PIN 需要管理员 PIN

$ oct pin --card ABCD:01234567 set-user

设置新的管理员 PIN

这需要（以前的）管理员 PIN。

$ oct pin --card ABCD:01234567 set-admin

使用管理员 PIN 重置用户 PIN

可以通过提供管理员 PIN 来将用户 PIN 重置为不同的（或相同的）PIN。这可以在任何时候进行，包括当输入错误的用户 PIN 太多次，并且卡拒绝接受用户 PIN 时。

$ oct pin --card ABCD:01234567 reset-user

配置重置代码

重置代码是恢复丢失或锁定用户 PIN 的另一种机制。

验证管理员PIN后，您可以设置重置码。一旦您的卡片上配置了重置码，您就可以使用该码重置用户PIN，而无需管理员PIN。

$ oct pin --card ABCD:01234567 set-reset

使用重置码重置用户PIN

如果卡片上配置了重置码，您可以使用该码重置用户PIN

$ oct pin --card ABCD:01234567 reset-user-rc
Enter resetting code:
Enter new User PIN:
Repeat the new User PIN:

User PIN has been set.

系统命令

"system"顶级命令组包含执行初始化和类似功能的命令。

工厂重置

工厂重置将擦除您卡片上的所有数据，包括卡片存储的私钥材料。

$ oct system factory-reset --card ABCD:01234567

注意：您无需PIN即可重置卡片！

设置身份

此命令仅适用于Nitrokey Start。

Nitrokey Start OpenPGP卡片可以呈现为3个独立的"虚拟"OpenPGP卡片，每个卡片都有一组OpenPGP密钥。要选择身份"1"，请运行

$ oct system set-identity --card ABCD:01234567 1

激活文件

此命令在正常操作中无用。但是，如果您的卡片意外进入"终止"状态，您可以使用此命令再次激活卡片。

此命令只能在恰好有一张卡片连接到您的系统且该卡片处于"终止"模式时使用。否则，该命令将打印错误信息并执行无操作。

$ oct system activate-file

在带PIN键盘的卡片读卡器上直接输入PIN

如果您的OpenPGP卡片插入带PIN键盘的卡片读卡器中，此工具为您提供了使用PIN键盘输入用户或管理员PIN的选项。为此，您可以省略-和/或-参数。然后您将在需要的地方被提示输入用户或管理员PIN。

$ oct --output-format json status
{
  "schema_version": "0.9.0",
  "ident": "ABCD:01234567",
  "card_version": "3.4",
  "cardholder_name": "Alice Adams",
  "language_preferences": [],
  "certificate_url": "http://alice.example/alice.pgp",
  "signature_key": {
    "fingerprint": "a3934505bc5111772e0b845a142cc9ab71265c00",
    "creation_time": "2022-10-31 13:45:35 UTC",
    "algorithm": "EdDSA (Ed25519)",
    "touch_policy": "Off",
    "touch_features": "Button",
    "status": "generated",
    "public_key_material": "ECC [EdDSA (Ed25519)], data: 3A2B88EF788FA59575E3C4DB89EE367DBD0D9E93B6CE26B7686D32E94958F32A"
  },
  "signature_count": 3,
  "user_pin_valid_for_only_one_signature": false,
  "decryption_key": {
    "fingerprint": "0643f2a966054158ccfab11fc7d20dbada6484e0",
    "creation_time": "2022-10-31 13:45:35 UTC",
    "algorithm": "ECDH (Curve25519)",
    "touch_policy": "Off",
    "touch_features": "Button",
    "status": "generated",
    "public_key_material": "ECC [ECDH (Curve25519)], data: AF97CA49B2D89998605985AEDAA19097A0CE7E5CC681B1ABD1C8610933FDB320"
  },
  "authentication_key": {
    "fingerprint": "2ba33b4290de337d1df854b32e20e5503abc57a9",
    "creation_time": "2022-10-31 13:45:35 UTC",
    "algorithm": "EdDSA (Ed25519)",
    "touch_policy": "Off",
    "touch_features": "Button",
    "status": "generated",
    "public_key_material": "ECC [EdDSA (Ed25519)], data: 80178ECE7F16ACDFDB0A645C81E72287761F03488CE3AE01F74279AA88A9018C"
  },
  "attestation_key": {
    "fingerprint": null,
    "creation_time": null,
    "algorithm": "RSA 2048 [e 17]",
    "touch_policy": "Off",
    "touch_features": "Button",
    "status": null,
    "public_key_material": null
  },
  "user_pin_remaining_attempts": 3,
  "admin_pin_remaining_attempts": 3,
  "reset_code_remaining_attempts": 0
}

$ oct sign --card ABCD:01234567 -p /dev/fd/3 detached 3<<<123456

$ oct admin --card ABCD:01234567 -P /dev/fd/3 generate -p /dev/fd/4 --output <output-cert-file> curve25519 3<<<12345678 4<<<123456

$ oct attestation cert
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----

$ oct attestation generate --key SIG --card 0006:01234567

$ oct attestation statement --key SIG
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----