Skip to content

PGPSecretKey: Document required Direct-Key Signatures. #2232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vanitasvitae wants to merge 2 commits into
base: main
Choose a base branch
from
+39 −33
Open

PGPSecretKey: Document required Direct-Key Signatures. #2232

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cba9a15
PGPSecretKey: Document the necessity to manually add direct-key sigs …
vanitasvitae Jan 19, 2026
9699a9d
PGPSecretKey: Lingua; replace master with primary
vanitasvitae Jan 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 39 additions & 33 deletions pg/src/main/java/org/bouncycastle/openpgp/PGPSecretKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,28 +78,28 @@ public PGPSecretKey(
* @param privKey the private key component.
* @param pubKey the public key component.
* @param checksumCalculator a calculator for the private key checksum
* @param isMasterKey true if the key is a master key, false otherwise.
* @param isPrimaryKey true if the key is a primary key, false otherwise.
* @param keyEncryptor an encryptor for the key if required (null otherwise).
* @throws PGPException if there is an issue creating the secret key packet.
*/
public PGPSecretKey(
PGPPrivateKey privKey,
PGPPublicKey pubKey,
PGPDigestCalculator checksumCalculator,
boolean isMasterKey,
boolean isPrimaryKey,
PBESecretKeyEncryptor keyEncryptor)
throws PGPException
{
this.pub = buildPublicKey(isMasterKey, pubKey);
this.secret = buildSecretKeyPacket(isMasterKey, privKey, pubKey, keyEncryptor, checksumCalculator);
this.pub = buildPublicKey(isPrimaryKey, pubKey);
this.secret = buildSecretKeyPacket(isPrimaryKey, privKey, pubKey, keyEncryptor, checksumCalculator);
}

private static PGPPublicKey buildPublicKey(boolean isMasterKey, PGPPublicKey pubKey)
private static PGPPublicKey buildPublicKey(boolean isPrimaryKey, PGPPublicKey pubKey)
{
PublicKeyPacket pubPacket = pubKey.publicPk;

// make sure we can actually do what's wanted
if (isMasterKey && !(pubKey.isEncryptionKey() && pubPacket.getAlgorithm() != PublicKeyAlgorithmTags.RSA_GENERAL))
if (isPrimaryKey && !(pubKey.isEncryptionKey() && pubPacket.getAlgorithm() != PublicKeyAlgorithmTags.RSA_GENERAL))
{
PGPPublicKey mstKey = new PGPPublicKey(pubKey);
mstKey.publicPk = new PublicKeyPacket(pubPacket.getVersion(), pubPacket.getAlgorithm(), pubPacket.getTime(), pubPacket.getKey());
Expand All @@ -113,14 +113,14 @@ private static PGPPublicKey buildPublicKey(boolean isMasterKey, PGPPublicKey pub
}
}

private static SecretKeyPacket buildSecretKeyPacket(boolean isMasterKey, PGPPrivateKey privKey, PGPPublicKey pubKey, PBESecretKeyEncryptor keyEncryptor, PGPDigestCalculator checksumCalculator)
private static SecretKeyPacket buildSecretKeyPacket(boolean isPrimaryKey, PGPPrivateKey privKey, PGPPublicKey pubKey, PBESecretKeyEncryptor keyEncryptor, PGPDigestCalculator checksumCalculator)
throws PGPException
{
BCPGObject secKey = (BCPGObject)privKey.getPrivateKeyDataPacket();

if (secKey == null)
{
return generateSecretKeyPacket(isMasterKey, pubKey.publicPk, SymmetricKeyAlgorithmTags.NULL, new byte[0]);
return generateSecretKeyPacket(isPrimaryKey, pubKey.publicPk, SymmetricKeyAlgorithmTags.NULL, new byte[0]);
}

try
Expand Down Expand Up @@ -149,7 +149,7 @@ private static SecretKeyPacket buildSecretKeyPacket(boolean isMasterKey, PGPPriv
if (keyEncryptor.getAeadAlgorithm() != 0)
{
s2kUsage = SecretKeyPacket.USAGE_AEAD;
return generateSecretKeyPacket(isMasterKey, pubKey.publicPk, encAlgorithm, keyEncryptor.getAeadAlgorithm(), s2kUsage, s2k, iv, encData);
return generateSecretKeyPacket(isPrimaryKey, pubKey.publicPk, encAlgorithm, keyEncryptor.getAeadAlgorithm(), s2kUsage, s2k, iv, encData);
}

if (checksumCalculator != null)
Expand All @@ -165,13 +165,13 @@ private static SecretKeyPacket buildSecretKeyPacket(boolean isMasterKey, PGPPriv
s2kUsage = SecretKeyPacket.USAGE_CHECKSUM;
}

return generateSecretKeyPacket(isMasterKey, pubKey.publicPk, encAlgorithm, s2kUsage, s2k, iv, encData);
return generateSecretKeyPacket(isPrimaryKey, pubKey.publicPk, encAlgorithm, s2kUsage, s2k, iv, encData);
}
else if (pubKey.getVersion() != PublicKeyPacket.VERSION_6)
{
pOut.write(checksum(null, keyData, keyData.length));
}
return generateSecretKeyPacket(isMasterKey, pubKey.publicPk, encAlgorithm, bOut.toByteArray());
return generateSecretKeyPacket(isPrimaryKey, pubKey.publicPk, encAlgorithm, bOut.toByteArray());
}
catch (PGPException e)
{
Expand All @@ -183,9 +183,9 @@ else if (pubKey.getVersion() != PublicKeyPacket.VERSION_6)
}
}

private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, PublicKeyPacket pubKey, int encAlgorithm, byte[] secKeyData)
private static SecretKeyPacket generateSecretKeyPacket(boolean isPrimaryKey, PublicKeyPacket pubKey, int encAlgorithm, byte[] secKeyData)
{
if (isMasterKey)
if (isPrimaryKey)
{
return new SecretKeyPacket(pubKey, encAlgorithm, null, null, secKeyData);
}
Expand All @@ -195,9 +195,9 @@ private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, Publ
}
}

private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, PublicKeyPacket pubKey, int encAlgorithm, int s2kusage, S2K s2k, byte[] iv, byte[] secKeyData)
private static SecretKeyPacket generateSecretKeyPacket(boolean isPrimaryKey, PublicKeyPacket pubKey, int encAlgorithm, int s2kusage, S2K s2k, byte[] iv, byte[] secKeyData)
{
if (isMasterKey)
if (isPrimaryKey)
{
return new SecretKeyPacket(pubKey, encAlgorithm, s2kusage, s2k, iv, secKeyData);
}
Expand All @@ -207,9 +207,9 @@ private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, Publ
}
}

private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, PublicKeyPacket pubKey, int encAlgorithm, int aeadAlgorithm, int s2kUsage, S2K s2K, byte[] iv, byte[] secKeyData)
private static SecretKeyPacket generateSecretKeyPacket(boolean isPrimaryKey, PublicKeyPacket pubKey, int encAlgorithm, int aeadAlgorithm, int s2kUsage, S2K s2K, byte[] iv, byte[] secKeyData)
{
if (isMasterKey)
if (isPrimaryKey)
{
return new SecretKeyPacket(pubKey, encAlgorithm, aeadAlgorithm, s2kUsage, s2K, iv, secKeyData);
}
Expand All @@ -221,8 +221,11 @@ private static SecretKeyPacket generateSecretKeyPacket(boolean isMasterKey, Publ

/**
* Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id
* using a generated certification of certificationLevel.The secret key checksum is calculated using the original
* using a generated certification of certificationLevel. The secret key checksum is calculated using the original
* non-digest based checksum.
* <p>
* Note: In case of a version 6 OpenPGP key, you need to manually add a direct-key self-signature on the primary
* key in order for it to be considered valid.
*
* @param certificationLevel the type of certification to be added.
* @param keyPair the public/private keys to use.
Expand All @@ -247,32 +250,32 @@ public PGPSecretKey(
}

/**
* Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair.
* Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the primary key pair.
* The secret key checksum is calculated using the passed in checksum calculator.
*
* @param masterKeyPair the master public/private keys for the new subkey.
* @param primaryKeyPair the primary public/private keys for the new subkey.
* @param keyPair the public/private keys to use.
* @param checksumCalculator a calculator for the private key checksum
* @param certificationSignerBuilder the builder for generating the certification.
* @param keyEncryptor an encryptor for the key if required (null otherwise).
* @throws PGPException if there is an issue creating the secret key packet or the certification.
*/
public PGPSecretKey(
PGPKeyPair masterKeyPair,
PGPKeyPair primaryKeyPair,
PGPKeyPair keyPair,
PGPDigestCalculator checksumCalculator,
PGPContentSignerBuilder certificationSignerBuilder,
PBESecretKeyEncryptor keyEncryptor)
throws PGPException
{
this(masterKeyPair, keyPair, checksumCalculator, null, null, certificationSignerBuilder, keyEncryptor);
this(primaryKeyPair, keyPair, checksumCalculator, null, null, certificationSignerBuilder, keyEncryptor);
}

/**
* Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the master key pair.
* Construct a PGPSecretKey sub-key using the passed in private/public key pair and binding it to the primary key pair.
* The secret key checksum is calculated using the passed in checksum calculator.
*
* @param masterKeyPair the master public/private keys for the new subkey.
* @param primaryKeyPair the primary public/private keys for the new subkey.
* @param keyPair the public/private keys to use.
* @param checksumCalculator calculator for PGP key checksums.
* @param hashedPcks the hashed packets to be added to the certification.
Expand All @@ -282,7 +285,7 @@ public PGPSecretKey(
* @throws PGPException if there is an issue creating the secret key packet or the certification.
*/
public PGPSecretKey(
PGPKeyPair masterKeyPair,
PGPKeyPair primaryKeyPair,
PGPKeyPair keyPair,
PGPDigestCalculator checksumCalculator,
PGPSignatureSubpacketVector hashedPcks,
Expand All @@ -294,9 +297,9 @@ public PGPSecretKey(
//
// generate the certification
//
PGPSignatureGenerator sGen = new PGPSignatureGenerator(certificationSignerBuilder, masterKeyPair.getPublicKey());
PGPSignatureGenerator sGen = new PGPSignatureGenerator(certificationSignerBuilder, primaryKeyPair.getPublicKey());

sGen.init(PGPSignature.SUBKEY_BINDING, masterKeyPair.getPrivateKey());
sGen.init(PGPSignature.SUBKEY_BINDING, primaryKeyPair.getPrivateKey());

// do some basic checking if we are a signing key.
if (!keyPair.getPublicKey().isEncryptionKey())
Expand All @@ -311,7 +314,7 @@ public PGPSecretKey(

try
{
subGen.addEmbeddedSignature(false, signatureGenerator.generateCertification(masterKeyPair.getPublicKey(), keyPair.getPublicKey()));
subGen.addEmbeddedSignature(false, signatureGenerator.generateCertification(primaryKeyPair.getPublicKey(), keyPair.getPublicKey()));

hashedPcks = subGen.generate();
}
Expand All @@ -331,7 +334,7 @@ else if (!hashedPcks.hasSubpacket(SignatureSubpacketTags.EMBEDDED_SIGNATURE))

List<PGPSignature> subSigs = new ArrayList<PGPSignature>();

subSigs.add(sGen.generateCertification(masterKeyPair.getPublicKey(), keyPair.getPublicKey()));
subSigs.add(sGen.generateCertification(primaryKeyPair.getPublicKey(), keyPair.getPublicKey()));

// replace the public key packet structure with a public subkey one.
PGPPublicKey pubSubKey = new PGPPublicKey(keyPair.getPublicKey(), null, subSigs);
Expand All @@ -345,9 +348,12 @@ else if (!hashedPcks.hasSubpacket(SignatureSubpacketTags.EMBEDDED_SIGNATURE))
/**
* Construct a PGPSecretKey using the passed in private/public key pair and binding it to the passed in id
* using a generated certification of certificationLevel.
* <p>
* Note: In case of a version 6 OpenPGP key, you need to manually add a direct-key self-signature on the primary
* key in order for it to be considered valid.
*
* @param certificationLevel the type of certification to be added.
* @param keyPair the public/private keys to use.
* @param keyPair the primary public/private keys to use.
* @param id the id to bind to the key.
* @param checksumCalculator a calculator for the private key checksum.
* @param hashedPcks the hashed packets to be added to the certification.
Expand Down Expand Up @@ -424,9 +430,9 @@ public boolean isSigningKey()
}

/**
* Return true if this is a master key.
* Return true if this is a primary key.
*
* @return true if a master key.
* @return true if a primary key.
*/
public boolean isMasterKey()
{
Expand All @@ -436,7 +442,7 @@ public boolean isMasterKey()
/**
* Detect if the Secret Key's Private Key is empty or not
*
* @return boolean whether or not the private key is empty
* @return boolean whether the private key is empty
*/
public boolean isPrivateKeyEmpty()
{
Expand Down