Package org.pgpainless.key.util

# Class KeyRingUtils

java.lang.Object
org.pgpainless.key.util.KeyRingUtils

public final class KeyRingUtils extends Object

## Method Summary

Modifier and Type
Method
Description
`static org.bouncycastle.openpgp.PGPSecretKeyRing`
`changePassphrase(Long keyId, org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, SecretKeyRingProtector oldProtector, SecretKeyRingProtector newProtector)`
`static org.bouncycastle.openpgp.PGPPublicKey`
`getPrimaryPublicKeyFrom(org.bouncycastle.openpgp.PGPKeyRing keyRing)`
Return the primary `PGPPublicKey` from the provided key ring or null if it has none.
`static org.bouncycastle.openpgp.PGPSecretKey`
`getPrimarySecretKeyFrom(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)`
Return the primary `PGPSecretKey` from the provided `PGPSecretKeyRing` or null if it has none.
`static org.bouncycastle.openpgp.PGPPublicKey`
`getPublicKeyFrom(org.bouncycastle.openpgp.PGPKeyRing keyRing, long subKeyId)`
Return the public key with the given subKeyId from the keyRing.
`static org.bouncycastle.openpgp.PGPPublicKey`
`getStrippedDownPublicKey(org.bouncycastle.openpgp.PGPPublicKey bloatedKey)`
Strip all user-ids, user-attributes and signatures from the given public key.
`static List<String>`
`getUserIdsIgnoringInvalidUTF8(org.bouncycastle.openpgp.PGPPublicKey key)`
`static <T extends org.bouncycastle.openpgp.PGPKeyRing>
T`
`injectCertification(T keyRing, String userId, org.bouncycastle.openpgp.PGPSignature certification)`
Inject a user-id certification into the given key ring.
`static <T extends org.bouncycastle.openpgp.PGPKeyRing>
T`
`injectCertification(T keyRing, org.bouncycastle.openpgp.PGPPublicKey certifiedKey, org.bouncycastle.openpgp.PGPSignature certification)`
Inject a key certification for the given key into the given key ring.
`static <T extends org.bouncycastle.openpgp.PGPKeyRing>
T`
`injectCertification(T keyRing, org.bouncycastle.openpgp.PGPSignature certification)`
Inject a key certification for the primary key into the given key ring.
`static <T extends org.bouncycastle.openpgp.PGPKeyRing>
T`
`injectCertification(T keyRing, org.bouncycastle.openpgp.PGPUserAttributeSubpacketVector userAttributes, org.bouncycastle.openpgp.PGPSignature certification)`
Inject a user-attribute vector certification into the given key ring.
`static boolean`
`keyRingContainsKeyWithId(org.bouncycastle.openpgp.PGPPublicKeyRing ring, long keyId)`
Return true, if the given `PGPPublicKeyRing` contains a `PGPPublicKey` for the given key id.
`static org.bouncycastle.openpgp.PGPPublicKeyRingCollection`
`keyRingsToKeyRingCollection(org.bouncycastle.openpgp.PGPPublicKeyRing... rings)`
Create a new `PGPPublicKeyRingCollection` from an array of `PGPPublicKeyRings`.
`static org.bouncycastle.openpgp.PGPSecretKeyRingCollection`
`keyRingsToKeyRingCollection(org.bouncycastle.openpgp.PGPSecretKeyRing... rings)`
Create a new `PGPSecretKeyRingCollection` from an array of `PGPSecretKeyRings`.
`static <T extends org.bouncycastle.openpgp.PGPKeyRing>
T`
`keysPlusPublicKey(T keyRing, org.bouncycastle.openpgp.PGPPublicKey publicKey)`
Inject a `PGPPublicKey` into the given key ring.
`static org.bouncycastle.openpgp.PGPSecretKeyRing`
`keysPlusSecretKey(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, org.bouncycastle.openpgp.PGPSecretKey secretKey)`
Inject a `PGPSecretKey` into a `PGPSecretKeyRing`.
`static org.bouncycastle.openpgp.PGPPublicKeyRingCollection`
`publicKeyRingCollectionFrom(org.bouncycastle.openpgp.PGPSecretKeyRingCollection secretKeyRings)`
Extract `PGPPublicKeyRings` from all `PGPSecretKeyRings` in the given `PGPSecretKeyRingCollection` and return them as a `PGPPublicKeyRingCollection`.
`static org.bouncycastle.openpgp.PGPPublicKeyRing`
`publicKeyRingFrom(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)`
Extract a `PGPPublicKeyRing` containing all public keys from the provided `PGPSecretKeyRing`.
`static org.bouncycastle.openpgp.PGPPublicKeyRing`
`publicKeys(org.bouncycastle.openpgp.PGPKeyRing keys)`
`static org.bouncycastle.openpgp.PGPSecretKey`
`reencryptPrivateKey(org.bouncycastle.openpgp.PGPSecretKey secretKey, SecretKeyRingProtector oldProtector, SecretKeyRingProtector newProtector)`
`static org.bouncycastle.openpgp.PGPPublicKey`
`requirePrimaryPublicKeyFrom(org.bouncycastle.openpgp.PGPKeyRing keyRing)`
Return the primary `PGPPublicKey` from the provided key ring.
`static org.bouncycastle.openpgp.PGPSecretKey`
`requirePrimarySecretKeyFrom(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)`
Return the primary `PGPSecretKey` from the provided `PGPSecretKeyRing`.
`static org.bouncycastle.openpgp.PGPPublicKey`
`requirePublicKeyFrom(org.bouncycastle.openpgp.PGPKeyRing keyRing, long subKeyId)`
Require the public key with the given subKeyId from the keyRing.
`static org.bouncycastle.openpgp.PGPSecretKey`
`requireSecretKeyFrom(org.bouncycastle.openpgp.PGPSecretKeyRing keyRing, long subKeyId)`
Require the secret key with the given secret subKeyId from the secret keyRing.
`static org.bouncycastle.openpgp.PGPSecretKeyRing`
`s2kUsageFixIfNecessary(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, SecretKeyRingProtector protector)`
`static org.bouncycastle.openpgp.PGPSecretKey`
`secretKeyPlusSignature(org.bouncycastle.openpgp.PGPSecretKey secretKey, org.bouncycastle.openpgp.PGPSignature signature)`
Inject the given signature into the public part of the given secret key.
`static org.bouncycastle.openpgp.PGPSecretKeyRing`
`stripSecretKey(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, long secretKeyId)`
Remove the secret key of the subkey identified by the given secret key id from the key ring.
`static org.bouncycastle.openpgp.PGPPrivateKey`
`unlockSecretKey(org.bouncycastle.openpgp.PGPSecretKey secretKey, SecretKeyRingProtector protector)`
Unlock a `PGPSecretKey` and return the resulting `PGPPrivateKey`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Method Details

### requirePrimarySecretKeyFrom

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKey requirePrimarySecretKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)
Return the primary `PGPSecretKey` from the provided `PGPSecretKeyRing`. If it has no primary secret key, throw a `NoSuchElementException`.

Parameters:
  `secretKeys` - secret keys
Returns:
  primary secret key

### getPrimarySecretKeyFrom

@Nullable public static org.bouncycastle.openpgp.PGPSecretKey getPrimarySecretKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)
Return the primary `PGPSecretKey` from the provided `PGPSecretKeyRing` or null if it has none.

Parameters:
  `secretKeys` - secret key ring
Returns:
  primary secret key

### requirePrimaryPublicKeyFrom

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKey requirePrimaryPublicKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing)
Return the primary `PGPPublicKey` from the provided key ring. Throws a `NoSuchElementException` if the key ring has no primary public key.

Parameters:
  `keyRing` - key ring
Returns:
  primary public key

### getPrimaryPublicKeyFrom

@Nullable public static org.bouncycastle.openpgp.PGPPublicKey getPrimaryPublicKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing)
Return the primary `PGPPublicKey` from the provided key ring or null if it has none.

Parameters:
  `keyRing` - key ring
Returns:
  primary public key

### getPublicKeyFrom

@Nullable public static org.bouncycastle.openpgp.PGPPublicKey getPublicKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing, long subKeyId)
Return the public key with the given subKeyId from the keyRing. If no such subkey exists, return null.

Parameters:
  `keyRing` - key ring
  `subKeyId` - subkey id
Returns:
  subkey or null

### requirePublicKeyFrom

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKey requirePublicKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing, long subKeyId)
Require the public key with the given subKeyId from the keyRing. If no such subkey exists, throw an `NoSuchElementException`.

Parameters:
  `keyRing` - key ring
  `subKeyId` - subkey id
Returns:
  subkey

### requireSecretKeyFrom

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKey requireSecretKeyFrom(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing keyRing, long subKeyId)
Require the secret key with the given secret subKeyId from the secret keyRing. If no such subkey exists, throw an `NoSuchElementException`.

Parameters:
  `keyRing` - secret key ring
  `subKeyId` - subkey id
Returns:
  secret subkey

### publicKeys

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKeyRing publicKeys(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keys)

### publicKeyRingFrom

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKeyRing publicKeyRingFrom(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys)
Extract a `PGPPublicKeyRing` containing all public keys from the provided `PGPSecretKeyRing`.

Parameters:
  `secretKeys` - secret key ring
Returns:
  public key ring

### publicKeyRingCollectionFrom

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKeyRingCollection publicKeyRingCollectionFrom(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRingCollection secretKeyRings)
Extract `PGPPublicKeyRings` from all `PGPSecretKeyRings` in the given `PGPSecretKeyRingCollection` and return them as a `PGPPublicKeyRingCollection`.

Parameters:
  `secretKeyRings` - secret key ring collection
Returns:
  public key ring collection

### unlockSecretKey

@Nonnull public static org.bouncycastle.openpgp.PGPPrivateKey unlockSecretKey(@Nonnull org.bouncycastle.openpgp.PGPSecretKey secretKey, @Nonnull SecretKeyRingProtector protector) throws org.bouncycastle.openpgp.PGPException
Unlock a `PGPSecretKey` and return the resulting `PGPPrivateKey`.

Parameters:
  `secretKey` - secret key
  `protector` - protector to unlock the secret key
Returns:
  private key
Throws:
  `org.bouncycastle.openpgp.PGPException` - if something goes wrong (e.g. wrong passphrase)

### keyRingsToKeyRingCollection

@Nonnull public static org.bouncycastle.openpgp.PGPPublicKeyRingCollection keyRingsToKeyRingCollection(@Nonnull org.bouncycastle.openpgp.PGPPublicKeyRing... rings)
Create a new `PGPPublicKeyRingCollection` from an array of `PGPPublicKeyRings`.

Parameters:
  `rings` - array of public key rings
Returns:
  key ring collection

### keyRingsToKeyRingCollection

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKeyRingCollection keyRingsToKeyRingCollection(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing... rings)
Create a new `PGPSecretKeyRingCollection` from an array of `PGPSecretKeyRings`.

Parameters:
  `rings` - array of secret key rings
Returns:
  secret key ring collection

### keyRingContainsKeyWithId

public static boolean keyRingContainsKeyWithId(@Nonnull org.bouncycastle.openpgp.PGPPublicKeyRing ring, long keyId)
Return true, if the given `PGPPublicKeyRing` contains a `PGPPublicKey` for the given key id.

Parameters:
  `ring` - public key ring
  `keyId` - id of the key in question
Returns:
  true if ring contains said key, false otherwise

### injectCertification

@Nonnull public static <T extends org.bouncycastle.openpgp.PGPKeyRing> T injectCertification(@Nonnull T keyRing, @Nonnull org.bouncycastle.openpgp.PGPSignature certification)
Inject a key certification for the primary key into the given key ring.

Type Parameters:
  `T` - either `PGPPublicKeyRing` or `PGPSecretKeyRing`
Parameters:
  `keyRing` - key ring
  `certification` - key signature
Returns:
  key ring with injected signature

### injectCertification

@Nonnull public static <T extends org.bouncycastle.openpgp.PGPKeyRing> T injectCertification(@Nonnull T keyRing, @Nonnull org.bouncycastle.openpgp.PGPPublicKey certifiedKey, @Nonnull org.bouncycastle.openpgp.PGPSignature certification)
Inject a key certification for the given key into the given key ring.

Type Parameters:
  `T` - either `PGPPublicKeyRing` or `PGPSecretKeyRing`
Parameters:
  `keyRing` - key ring
  `certifiedKey` - signed public key
  `certification` - key signature
Returns:
  key ring with injected signature
Throws:
  `NoSuchElementException` - in case that the signed key is not part of the key ring

### injectCertification

@Nonnull public static <T extends org.bouncycastle.openpgp.PGPKeyRing> T injectCertification(@Nonnull T keyRing, @Nonnull String userId, @Nonnull org.bouncycastle.openpgp.PGPSignature certification)
Inject a user-id certification into the given key ring.

Type Parameters:
  `T` - either `PGPPublicKeyRing` or `PGPSecretKeyRing`
Parameters:
  `keyRing` - key ring
  `userId` - signed user-id
  `certification` - signature
Returns:
  key ring with injected certification

### injectCertification

@Nonnull public static <T extends org.bouncycastle.openpgp.PGPKeyRing> T injectCertification(@Nonnull T keyRing, @Nonnull org.bouncycastle.openpgp.PGPUserAttributeSubpacketVector userAttributes, @Nonnull org.bouncycastle.openpgp.PGPSignature certification)
Inject a user-attribute vector certification into the given key ring.

Type Parameters:
  `T` - either `PGPPublicKeyRing` or `PGPSecretKeyRing`
Parameters:
  `keyRing` - key ring
  `userAttributes` - certified user attributes
  `certification` - certification signature
Returns:
  key ring with injected user-attribute certification

### keysPlusPublicKey

@Nonnull public static <T extends org.bouncycastle.openpgp.PGPKeyRing> T keysPlusPublicKey(@Nonnull T keyRing, @Nonnull org.bouncycastle.openpgp.PGPPublicKey publicKey)
Inject a `PGPPublicKey` into the given key ring.

Type Parameters:
  `T` - either `PGPPublicKeyRing` or `PGPSecretKeyRing`
Parameters:
  `keyRing` - key ring
  `publicKey` - public key
Returns:
  key ring with injected public key

### keysPlusSecretKey

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKeyRing keysPlusSecretKey(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, @Nonnull org.bouncycastle.openpgp.PGPSecretKey secretKey)
Inject a `PGPSecretKey` into a `PGPSecretKeyRing`.

Parameters:
  `secretKeys` - secret key ring
  `secretKey` - secret key
Returns:
  secret key ring with injected secret key

### secretKeyPlusSignature

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKey secretKeyPlusSignature(@Nonnull org.bouncycastle.openpgp.PGPSecretKey secretKey, @Nonnull org.bouncycastle.openpgp.PGPSignature signature)
Inject the given signature into the public part of the given secret key.

Parameters:
  `secretKey` - secret key
  `signature` - signature
Returns:
  secret key with the signature injected in its public key

### stripSecretKey

@Nonnull public static org.bouncycastle.openpgp.PGPSecretKeyRing stripSecretKey(@Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, long secretKeyId) throws IOException, org.bouncycastle.openpgp.PGPException
Remove the secret key of the subkey identified by the given secret key id from the key ring. The public part stays attached to the key ring, so that it can still be used for encryption / verification of signatures. This method is intended to be used to remove secret primary keys from live keys when those are kept in offline storage.

Parameters:
  `secretKeys` - secret key ring
  `secretKeyId` - id of the secret key to remove
Returns:
  secret key ring with removed secret key
Throws:
  `IOException` - in case of an error during serialization / deserialization of the key
  `org.bouncycastle.openpgp.PGPException` - in case of a broken key

### getStrippedDownPublicKey

public static org.bouncycastle.openpgp.PGPPublicKey getStrippedDownPublicKey(org.bouncycastle.openpgp.PGPPublicKey bloatedKey) throws org.bouncycastle.openpgp.PGPException
Strip all user-ids, user-attributes and signatures from the given public key.

Parameters:
  `bloatedKey` - public key
Returns:
  stripped public key
Throws:
  `org.bouncycastle.openpgp.PGPException` - if the packet is faulty or the required calculations fail

### getUserIdsIgnoringInvalidUTF8

public static List<String> getUserIdsIgnoringInvalidUTF8(org.bouncycastle.openpgp.PGPPublicKey key)

### changePassphrase

public static org.bouncycastle.openpgp.PGPSecretKeyRing changePassphrase(Long keyId, org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, SecretKeyRingProtector oldProtector, SecretKeyRingProtector newProtector) throws org.bouncycastle.openpgp.PGPException

Throws:
  `org.bouncycastle.openpgp.PGPException`

### reencryptPrivateKey

public static org.bouncycastle.openpgp.PGPSecretKey reencryptPrivateKey(org.bouncycastle.openpgp.PGPSecretKey secretKey, SecretKeyRingProtector oldProtector, SecretKeyRingProtector newProtector) throws org.bouncycastle.openpgp.PGPException

Throws:
  `org.bouncycastle.openpgp.PGPException`

### s2kUsageFixIfNecessary

public static org.bouncycastle.openpgp.PGPSecretKeyRing s2kUsageFixIfNecessary(org.bouncycastle.openpgp.PGPSecretKeyRing secretKeys, SecretKeyRingProtector protector) throws org.bouncycastle.openpgp.PGPException

Throws:
  `org.bouncycastle.openpgp.PGPException`