pgsc: OpenPGP smart card signature support, with the raw sign and decrypt operations moved onto OpenPGPSmartCard so a backend can be emulated in software, incorporating github PR #2430.

Author: vanitasvitae

CONTRIBUTORS.md

@@ -388,7 +388,7 @@ We also wish to acknowledge financial and collaborative support from [CISCO](htt
 - Adam Vartanian \<https://github.com/flooey\> use of ShortBuffer exception and buffer size pre-check in Cipher.doFinal().
 - Bernd \<https://github.com/ecki\> Fix to make PGPUtil.pipeFileContents use buffer and not leak file handle.
 - Shartung \<https://github.com/shartung\> Additional EC Key Agreement algorithms in support of German BSI TR-03111.
-- Paul Schaub \<https://github.com/vanitasvitae\> bringing PGPSecretKey.getUserIds() into line with PGPPublicKey.getUserIds(). Exception message fix in BcPublicKeyDataDecryptorFactory. Additional tests on PGP key ring generation. Improved functionality of PGPSignatureSubpacketGenerator, PGPPublicKeyRing. Tweaks to PGPDataEncryptorBuilder interface, fix for JcaPGP/BcPGP Ed25519 private key conversion. Added configurable CRC detection to ArmoredInputStream, additional control character skipping in ArmoredInputStream. Rewind code for PGPPBEEncryptedData, addition of PGPSignature.getDigestPrefix(). Wrong list traversal fix in PGPSecretKeyRing. Further improvement to use of generics in PGP API. General interop improvements. PGP Public / Secure keyring ignore marker packets when reading. Initial work on PGP session key handling, filtering literal data for canoncialization. Addition of direct key identified key-ring construction. PGPSecretKeyRing.insertOrReplacePublicKey addition. Addition of utility methods for joining/merging signatures and public keys. Addition of PGP regexp packet, PolicyURI packet handling, UTF8 comment testing. Efficiency improvements to TruncatedStream. Initial Argon2 support for OpenPGP. General cleanups. Fast CRC24 implementation, SHA3 addtions to BcImplProvider, improvements to One Pass Signature support, signatue validation, read() consistency in BCPGInputStream. Contributions to AEAD support (v6 & v5) in PGP API. Addition of PGP WildCard ID, moving the PGP example code into the 21st century. Security patches for encrypted data generation, initial thread safe certification verification. Support for V6 EC keys, V6 signatures, V6 encryption, V6 PKESK, PGP packet criticality, and Preferred AEAD CipherSuites sigsubpacket support. Introduce high-level OpenPGP API for message creation/consumption and certificate evaluation. OpenPGP fuzz testing. Fix to prevent a null pointer exception on processing a partial stripped key. Moving the Argon2 memory size exponent bounds check from S2K packet parsing to decryption time. ArmoredInputStream CSF dash-escape hardening. Report and initial patch for OnePassSignaturePacket defaulting to the Legacy packet format for v6 packets (github #2347). PGPKeyPairGenerator factory methods for the OpenPGP brainpool curves (github #2375). Support for OpenPGP External Secret Keys, and the initial OpenPGP smart card API (bcpgsc) with YubiKey and simulator backends (github #2339). Initial implementation of the JCE bindings for smart card decryption and the pluggable YubiKey decryptor factory provider (github #2374). Correcting MessageEncryptionMechanism.unencrypted() to report no encryption mode rather than SEIPDv1.
+- Paul Schaub \<https://github.com/vanitasvitae\> bringing PGPSecretKey.getUserIds() into line with PGPPublicKey.getUserIds(). Exception message fix in BcPublicKeyDataDecryptorFactory. Additional tests on PGP key ring generation. Improved functionality of PGPSignatureSubpacketGenerator, PGPPublicKeyRing. Tweaks to PGPDataEncryptorBuilder interface, fix for JcaPGP/BcPGP Ed25519 private key conversion. Added configurable CRC detection to ArmoredInputStream, additional control character skipping in ArmoredInputStream. Rewind code for PGPPBEEncryptedData, addition of PGPSignature.getDigestPrefix(). Wrong list traversal fix in PGPSecretKeyRing. Further improvement to use of generics in PGP API. General interop improvements. PGP Public / Secure keyring ignore marker packets when reading. Initial work on PGP session key handling, filtering literal data for canoncialization. Addition of direct key identified key-ring construction. PGPSecretKeyRing.insertOrReplacePublicKey addition. Addition of utility methods for joining/merging signatures and public keys. Addition of PGP regexp packet, PolicyURI packet handling, UTF8 comment testing. Efficiency improvements to TruncatedStream. Initial Argon2 support for OpenPGP. General cleanups. Fast CRC24 implementation, SHA3 addtions to BcImplProvider, improvements to One Pass Signature support, signatue validation, read() consistency in BCPGInputStream. Contributions to AEAD support (v6 & v5) in PGP API. Addition of PGP WildCard ID, moving the PGP example code into the 21st century. Security patches for encrypted data generation, initial thread safe certification verification. Support for V6 EC keys, V6 signatures, V6 encryption, V6 PKESK, PGP packet criticality, and Preferred AEAD CipherSuites sigsubpacket support. Introduce high-level OpenPGP API for message creation/consumption and certificate evaluation. OpenPGP fuzz testing. Fix to prevent a null pointer exception on processing a partial stripped key. Moving the Argon2 memory size exponent bounds check from S2K packet parsing to decryption time. ArmoredInputStream CSF dash-escape hardening. Report and initial patch for OnePassSignaturePacket defaulting to the Legacy packet format for v6 packets (github #2347). PGPKeyPairGenerator factory methods for the OpenPGP brainpool curves (github #2375). Support for OpenPGP External Secret Keys, and the initial OpenPGP smart card API (bcpgsc) with YubiKey and simulator backends (github #2339). Initial implementation of the JCE bindings for smart card decryption and the pluggable YubiKey decryptor factory provider (github #2374). Correcting MessageEncryptionMechanism.unencrypted() to report no encryption mode rather than SEIPDv1. Initial implementation of OpenPGP smart card signature support: the low-level sign and decrypt operations moved onto OpenPGPSmartCard so a backend can be emulated in software, external-key detection in the document signature generators, a pluggable PGPContentSignerBuilderProviderFactory, the generalised smart-card decryptor factories and the key conversion helpers (PR #2430).
 - Nick of Nexxar \<https://github.com/nros\> update to OpenPGP package to handle a broader range of EC curves.
 - catbref \<https://github.com/catbref\> sample implementation of RFC 7748/Ed25519 (incorporated work from github users Valodim and str4d as well).
 - gerlion \<https://github.com/gerlion\> detection of concurrency issue with pre-1.60 EC math library.

docs/releasenotes.md

@@ -35,6 +35,8 @@ Date: 2026, TBD
 
 ### 2.1.3 Additional Features and Functionality
 
+- The OpenPGP smart card API (bcpgsc) can now create signatures on a card as well as decrypt with one. The raw sign and decrypt operations moved onto OpenPGPSmartCard, so a backend can be emulated in software and the simulator exercises the same paths a card does; AbstractOpenPGPDocumentSignatureGenerator detects an external key and routes it to the card, with the content signer supplied through a pluggable PGPContentSignerBuilderProviderFactory; the YubiKey-specific decryptor factories are replaced by generic smart-card ones, ExternalOpenPGPKeyUtils converts an OpenPGPKey or OpenPGPCertificate into an external key, and the YubiKit dependency moves to 3.2.0. YubiKit remains compileOnly, so bcpgsc still ships with no third-party dependencies (github PR #2430).
+
 - The promoted LMS private key (org.bouncycastle.crypto.params.LMSPrivateKeyParameters) keeps its Merkle tree in two bounded tiers in place of the WeakHashMap that held every node it ever computed: the top 63 nodes - the same ones its encoding persists - in a fixed array for the life of the key, and the authentication path of the last one-time key signed with, together with that leaf's ancestors, advanced under the key's lock as each index is claimed. The old map keyed every node below the top on objects nothing retained, so a leaf was collectable the moment it was inserted and the map's hit rate below the top depended on when the collector next ran, while its table still grew to 2^(h+1) entries during a tree build. A run of consecutive signatures now costs about (h - 5) / 2 + 1 leaf derivations each rather than either a cache hit or a 2^(h - 5) rebuild, with the rebuild remaining as the worst case at a half-tree crossing; shards and repositioned keys inherit the parent's retained path, and the encoding is unchanged. The tree built for the public key is built in path form, so a freshly generated key already holds the path of its first signature rather than rebuilding it - that signature went from 2.6 s to about 1 ms at h=15. The deprecated org.bouncycastle.pqc.crypto.lms copy is untouched.
 
 ### 2.1.4 Additional Notes

pg/src/main/java/org/bouncycastle/openpgp/PGPSignatureGenerator.java

@@ -18,6 +18,7 @@
 import org.bouncycastle.crypto.CryptoServicesRegistrar;
 import org.bouncycastle.openpgp.operator.PGPContentSigner;
 import org.bouncycastle.openpgp.operator.PGPContentSignerBuilder;
+import org.bouncycastle.openpgp.operator.PGPExternalContentSignerBuilder;
 import org.bouncycastle.util.Arrays;
 import org.bouncycastle.util.Strings;
 
@@ -90,7 +91,7 @@ public PGPSignatureGenerator(
     }
 
     /**
-     * Initialise the generator for signing.
+     * Initialize the generator for signing.
      *
      * @param signatureType type of signature
      * @param key private signing key
@@ -105,7 +106,20 @@ public void init(
         {
             throw new PGPException("Illegal signature type 0xFF provided.");
         }
-        contentSigner = contentSignerBuilder.build(signatureType, key);
+
+        if (contentSignerBuilder instanceof PGPExternalContentSignerBuilder)
+        {
+            contentSigner = ((PGPExternalContentSignerBuilder)contentSignerBuilder).build(signatureType);
+        }
+        else if (key != null)
+        {
+            contentSigner = contentSignerBuilder.build(signatureType, key);
+        }
+        else
+        {
+            throw new PGPException("Missing private key.");
+        }
+
         sigOut = contentSigner.getOutputStream();
         sigType = contentSigner.getType();
         lastb = 0;
@@ -115,7 +129,7 @@ public void init(
             throw new PGPException("key algorithm mismatch");
         }
 
-        if (key.getPublicKeyPacket().getVersion() != version)
+        if (key != null && key.getPublicKeyPacket().getVersion() != version)
         {
             throw new PGPException("Key version mismatch.");
         }

pg/src/main/java/org/bouncycastle/openpgp/PGPUtil.java

@@ -18,8 +18,11 @@
 import org.bouncycastle.asn1.cryptlib.CryptlibObjectIdentifiers;
 import org.bouncycastle.asn1.edec.EdECObjectIdentifiers;
 import org.bouncycastle.asn1.gnu.GNUObjectIdentifiers;
+import org.bouncycastle.asn1.nist.NISTObjectIdentifiers;
+import org.bouncycastle.asn1.pkcs.PKCSObjectIdentifiers;
 import org.bouncycastle.asn1.sec.SECObjectIdentifiers;
 import org.bouncycastle.asn1.teletrust.TeleTrusTObjectIdentifiers;
+import org.bouncycastle.asn1.x509.X509ObjectIdentifiers;
 import org.bouncycastle.asn1.x9.ECNamedCurveTable;
 import org.bouncycastle.bcpg.ArmoredInputStream;
 import org.bouncycastle.bcpg.BCPGInputStream;
@@ -83,6 +86,37 @@ public class PGPUtil
         }
     };
 
+    public static ASN1ObjectIdentifier getDigestIdentifier(int hashAlgorithmId)
+            throws PGPException
+    {
+        switch (hashAlgorithmId)
+        {
+            case MD5:
+                return PKCSObjectIdentifiers.md5;
+            case SHA1:
+                return X509ObjectIdentifiers.id_SHA1;
+            case SHA224:
+                return NISTObjectIdentifiers.id_sha224;
+            case SHA256:
+                return NISTObjectIdentifiers.id_sha256;
+            case SHA384:
+                return NISTObjectIdentifiers.id_sha384;
+            case SHA512:
+                return NISTObjectIdentifiers.id_sha512;
+            case SHA3_224:
+                return NISTObjectIdentifiers.id_sha3_224;
+            case SHA3_256:
+                return NISTObjectIdentifiers.id_sha3_256;
+            case SHA3_384:
+                return NISTObjectIdentifiers.id_sha3_384;
+            case SHA3_512:
+                return NISTObjectIdentifiers.id_sha3_512;
+            case RIPEMD160:
+                return TeleTrusTObjectIdentifiers.ripemd128;
+        }
+        throw new PGPException("unknown hash algorithm id: " + hashAlgorithmId);
+    }
+
     /**
      * Return an appropriate name for the hash algorithm represented by the passed
      * in hash algorithm ID number.

pg/src/main/java/org/bouncycastle/openpgp/api/AbstractOpenPGPDocumentSignatureGenerator.java

@@ -3,14 +3,20 @@
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.Iterator;
+import java.util.LinkedHashSet;
 import java.util.List;
+import java.util.Set;
 
 import org.bouncycastle.bcpg.sig.PreferredAlgorithms;
 import org.bouncycastle.openpgp.PGPException;
 import org.bouncycastle.openpgp.PGPKeyPair;
+import org.bouncycastle.openpgp.PGPPublicKey;
 import org.bouncycastle.openpgp.PGPSignatureGenerator;
 import org.bouncycastle.openpgp.api.exception.InvalidSigningKeyException;
 import org.bouncycastle.openpgp.api.exception.KeyPassphraseException;
+import org.bouncycastle.openpgp.api.operator.PGPContentSignerBuilderProviderFactory;
+import org.bouncycastle.openpgp.operator.PGPContentSignerBuilder;
+import org.bouncycastle.openpgp.operator.PGPContentSignerBuilderProvider;
 
 public class AbstractOpenPGPDocumentSignatureGenerator<T extends AbstractOpenPGPDocumentSignatureGenerator<T>>
 {
@@ -23,6 +29,7 @@ public class AbstractOpenPGPDocumentSignatureGenerator<T extends AbstractOpenPGP
     protected final List<OpenPGPKey.OpenPGPSecretKey> signingKeys = new ArrayList<OpenPGPKey.OpenPGPSecretKey>();
     protected final List<SignatureParameters.Callback> signatureCallbacks = new ArrayList<SignatureParameters.Callback>();
     protected final List<KeyPassphraseProvider> signingKeyPassphraseProviders = new ArrayList<KeyPassphraseProvider>();
+    protected final Set<PGPContentSignerBuilderProviderFactory> customContentSignerBuilderProviderFactories = new LinkedHashSet<PGPContentSignerBuilderProviderFactory>();
 
     protected final KeyPassphraseProvider.DefaultKeyPassphraseProvider defaultKeyPassphraseProvider =
         new KeyPassphraseProvider.DefaultKeyPassphraseProvider();
@@ -81,6 +88,18 @@ public T addKeyPassphrase(char[] passphrase)
         return (T)this;
     }
 
+    /**
+     * Add a custom {@link PGPContentSignerBuilderProviderFactory} for external key signing.
+     * This is useful to allow e.g. signing with keys stored on hardware tokens or smart cards.
+     * @param factory custom factory
+     * @return this
+     */
+    public T addCustomPGPContentSignerBuilderProviderFactory(PGPContentSignerBuilderProviderFactory factory)
+    {
+        customContentSignerBuilderProviderFactories.add(factory);
+        return (T)this;
+    }
+
     /**
      * Add an {@link OpenPGPKey} for message signing.
      * The {@link #signingKeySelector} is responsible for selecting one or more subkeys of the key to sign with.
@@ -243,15 +262,59 @@ protected PGPSignatureGenerator initSignatureGenerator(
             throw new InvalidSigningKeyException(signingKey);
         }
 
-        char[] passphrase = passphraseProvider.getKeyPassword(signingKey);
-        PGPKeyPair unlockedKey = signingKey.unlock(passphrase).getKeyPair();
-        if (unlockedKey == null)
+        if (signingKey.getPGPSecretKey().isExternalKey())
         {
-            throw new KeyPassphraseException(signingKey, new PGPException("Cannot unlock secret key."));
+            PGPPublicKey publicKey = signingKey.getPGPPublicKey();
+            for (PGPContentSignerBuilderProviderFactory sigFac : customContentSignerBuilderProviderFactories)
+            {
+                PGPContentSignerBuilderProvider sigProv;
+                try
+                {
+                    sigProv = sigFac.getPGPContentSignerBuilderProvider(
+                            signingKey, passphraseProvider, parameters.getSignatureHashAlgorithmId());
+                    if (sigProv == null)
+                    {
+                        // no matching card found
+                        continue;
+                    }
+                }
+                catch (PGPException e)
+                {
+                    // No matching card found
+                    continue;
+                }
+
+                PGPContentSignerBuilder contentSignerBuilder;
+                try
+                {
+                    contentSignerBuilder = sigProv.get(publicKey);
+                }
+                catch (IllegalArgumentException e)
+                {
+                    // Mismatched key
+                    continue;
+                }
+
+                PGPSignatureGenerator sigGen = new PGPSignatureGenerator(contentSignerBuilder, publicKey);
+                sigGen.init(parameters.getSignatureType(), null);
+
+                return Utils.applyDefaultSubpackets(publicKey, parameters, parameters.getSignatureCreationTime(), null, sigGen);
+            }
+
+            throw new PGPException("Cannot initialize signature generator for external key " + signingKey.getKeyIdentifier());
         }
+        else
+        {
+            char[] passphrase = passphraseProvider.getKeyPassword(signingKey);
+            PGPKeyPair unlockedKey = signingKey.unlock(passphrase).getKeyPair();
+            if (unlockedKey == null)
+            {
+                throw new KeyPassphraseException(signingKey, new PGPException("Cannot unlock secret key."));
+            }
 
-        return Utils.getPgpSignatureGenerator(implementation, signingKey.getPGPPublicKey(),
-            unlockedKey.getPrivateKey(), parameters, parameters.getSignatureCreationTime(), null);
+            return Utils.getPgpSignatureGenerator(implementation, signingKey.getPGPPublicKey(),
+                    unlockedKey.getPrivateKey(), parameters, parameters.getSignatureCreationTime(), null);
+        }
     }
 
     private int getPreferredHashAlgorithm(OpenPGPCertificate.OpenPGPComponentKey key)

pg/src/main/java/org/bouncycastle/openpgp/api/OpenPGPMessageProcessor.java

@@ -575,6 +575,12 @@ void onException(PGPException e)
         }
     }
 
+    public OpenPGPMessageProcessor setExceptionCallback(PGPExceptionCallback callback)
+    {
+        this.configuration.exceptionCallback = callback;
+        return this;
+    }
+
     /**
      * Recover the session key of the given PKESK using the given secret key.
      * <p>

pg/src/main/java/org/bouncycastle/openpgp/api/Utils.java

@@ -88,6 +88,16 @@ static PGPSignatureGenerator getPgpSignatureGenerator(OpenPGPImplementation impl
             publicKey);
         sigGen.init(parameters.getSignatureType(), privateKey);
 
+        return applyDefaultSubpackets(publicKey, parameters, date, operation, sigGen);
+    }
+
+    static PGPSignatureGenerator applyDefaultSubpackets(PGPPublicKey publicKey,
+                                                        SignatureParameters parameters,
+                                                        Date date,
+                                                        HashedSubpacketsOperation operation,
+                                                        PGPSignatureGenerator sigGen)
+            throws PGPException
+    {
         final PGPSignatureSubpacketGenerator hashedSubpackets = new PGPSignatureSubpacketGenerator();
         hashedSubpackets.setIssuerFingerprint(true, publicKey);
         if (date != null)

pg/src/main/java/org/bouncycastle/openpgp/api/exception/KeyPassphraseException.java

@@ -7,6 +7,12 @@ public class KeyPassphraseException
 {
     private final Exception cause;
 
+    public KeyPassphraseException(OpenPGPCertificate.OpenPGPComponentKey key, String message, Exception cause)
+    {
+        super(key, message + "\n" + componentKeyErrorMessage(key, cause));
+        this.cause = cause;
+    }
+
     public KeyPassphraseException(OpenPGPCertificate.OpenPGPComponentKey key, Exception cause)
     {
         super(key, componentKeyErrorMessage(key, cause));

pg/src/main/java/org/bouncycastle/openpgp/api/jcajce/JcaOpenPGPImplementation.java

@@ -65,6 +65,11 @@ public JcaOpenPGPImplementation(Provider provider, SecureRandom secureRandom)
         this.secureRandom = secureRandom;
     }
 
+    public Provider getProvider()
+    {
+        return provider;
+    }
+
     @Override
     public PGPObjectFactory pgpObjectFactory(InputStream packetInputStream)
     {