Package org.pgpainless.key.protection

# Class CachingSecretKeyRingProtector

java.lang.Object
org.pgpainless.key.protection.CachingSecretKeyRingProtector

All Implemented Interfaces:
  `SecretKeyPassphraseProvider`, `SecretKeyRingProtector`

public class CachingSecretKeyRingProtector extends Object implements SecretKeyRingProtector, SecretKeyPassphraseProvider
Implementation of the `SecretKeyRingProtector` which holds a map of key ids and their passwords. In case the needed passphrase is not contained in the map, the `missingPassphraseCallback` will be consulted, and the passphrase is added to the map. If you need to unlock multiple `PGPKeyRings`, it is advised to use a separate `CachingSecretKeyRingProtector` instance for each ring.

## Constructor Summary

Constructors
Constructor
Description
`CachingSecretKeyRingProtector()`
`CachingSecretKeyRingProtector(Map<Long,Passphrase> passphrases, KeyRingProtectionSettings protectionSettings, SecretKeyPassphraseProvider missingPassphraseCallback)`
`CachingSecretKeyRingProtector(SecretKeyPassphraseProvider missingPassphraseCallback)`

## Method Summary

Modifier and Type
Method
Description
`void`
`addPassphrase(Long keyId, Passphrase passphrase)`
Add a passphrase to the cache.
`void`
`addPassphrase(org.bouncycastle.openpgp.PGPKeyRing keyRing, Passphrase passphrase)`
Remember the given passphrase for all keys in the given key ring.
`void`
`addPassphrase(org.bouncycastle.openpgp.PGPPublicKey key, Passphrase passphrase)`
Remember the given passphrase for the given (sub-)key.
`void`
`addPassphrase(OpenPgpFingerprint fingerprint, Passphrase passphrase)`
`void`
`forgetPassphrase(Long keyId)`
Remove a passphrase from the cache.
`void`
`forgetPassphrase(org.bouncycastle.openpgp.PGPKeyRing keyRing)`
Forget the passphrase to all keys in the provided key ring.
`void`
`forgetPassphrase(org.bouncycastle.openpgp.PGPPublicKey key)`
Forget the passphrase of the given public key.
`org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor`
`getDecryptor(Long keyId)`
Return a decryptor for the key of id `keyId`.
`org.bouncycastle.openpgp.operator.PBESecretKeyEncryptor`
`getEncryptor(Long keyId)`
Return an encryptor for the key of id `keyId`.
`Passphrase`
`getPassphraseFor(Long keyId)`
Return a passphrase for the given key.
`boolean`
`hasPassphrase(Long keyId)`
`boolean`
`hasPassphraseFor(Long keyId)`
Returns true, if the protector has a passphrase for the key with the given key-id.
`void`
`replacePassphrase(Long keyId, Passphrase passphrase)`
Replace the passphrase for the given key-id in the cache.
`void`
`replacePassphrase(org.bouncycastle.openpgp.PGPKeyRing keyRing, Passphrase passphrase)`
Replace the cached passphrases for all keys in the key ring with the provided passphrase.

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

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

### Methods inherited from interface org.pgpainless.key.protection.passphrase_provider.SecretKeyPassphraseProvider

`getPassphraseFor`

## Constructor Details

### CachingSecretKeyRingProtector

public CachingSecretKeyRingProtector()

### CachingSecretKeyRingProtector

public CachingSecretKeyRingProtector(@Nullable SecretKeyPassphraseProvider missingPassphraseCallback)

### CachingSecretKeyRingProtector

public CachingSecretKeyRingProtector(@Nonnull Map<Long,Passphrase> passphrases, @Nonnull KeyRingProtectionSettings protectionSettings, @Nullable SecretKeyPassphraseProvider missingPassphraseCallback)

## Method Details

### addPassphrase

public void addPassphrase(@Nonnull Long keyId, @Nonnull Passphrase passphrase)
Add a passphrase to the cache. If the cache already contains a passphrase for the given key-id, a `IllegalArgumentException` is thrown. The reason for this is to prevent accidental override of passphrases when dealing with multiple key rings containing a key with the same key-id but different passphrases. If you can ensure that there will be no key-id clash, and you want to replace the passphrase, you can use `replacePassphrase(Long, Passphrase)` to replace the passphrase.

Parameters:
  `keyId` - id of the key
  `passphrase` - passphrase

### replacePassphrase

public void replacePassphrase(@Nonnull Long keyId, @Nonnull Passphrase passphrase)
Replace the passphrase for the given key-id in the cache.

Parameters:
  `keyId` - keyId
  `passphrase` - passphrase

### addPassphrase

public void addPassphrase(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing, @Nonnull Passphrase passphrase)
Remember the given passphrase for all keys in the given key ring. If for the key-id of any key on the key ring the cache already contains a passphrase, a `IllegalArgumentException` is thrown before any changes are committed to the cache. This is to prevent accidental passphrase override when dealing with multiple key rings containing keys with conflicting key-ids. If you can ensure that there will be no key-id clashes, and you want to replace the passphrases for the key ring, use `replacePassphrase(PGPKeyRing, Passphrase)` instead. If you need to unlock multiple `PGPKeyRings`, it is advised to use a separate `CachingSecretKeyRingProtector` instance for each ring.

Parameters:
  `keyRing` - key ring
  `passphrase` - passphrase

### replacePassphrase

public void replacePassphrase(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing, @Nonnull Passphrase passphrase)
Replace the cached passphrases for all keys in the key ring with the provided passphrase.

Parameters:
  `keyRing` - key ring
  `passphrase` - passphrase

### addPassphrase

public void addPassphrase(@Nonnull org.bouncycastle.openpgp.PGPPublicKey key, @Nonnull Passphrase passphrase)
Remember the given passphrase for the given (sub-)key.

Parameters:
  `key` - key
  `passphrase` - passphrase

### addPassphrase

public void addPassphrase(@Nonnull OpenPgpFingerprint fingerprint, @Nonnull Passphrase passphrase)

### forgetPassphrase

public void forgetPassphrase(@Nonnull Long keyId)
Remove a passphrase from the cache. The passphrase will be cleared and then removed.

Parameters:
  `keyId` - id of the key

### forgetPassphrase

public void forgetPassphrase(@Nonnull org.bouncycastle.openpgp.PGPKeyRing keyRing)
Forget the passphrase to all keys in the provided key ring.

Parameters:
  `keyRing` - key ring

### forgetPassphrase

public void forgetPassphrase(@Nonnull org.bouncycastle.openpgp.PGPPublicKey key)
Forget the passphrase of the given public key.

Parameters:
  `key` - key

### getPassphraseFor

@Nullable public Passphrase getPassphraseFor(Long keyId)
Description copied from interface: `SecretKeyPassphraseProvider`
Return a passphrase for the given key. If no record has been found, return null. Note: In case of an unprotected secret key, this method must may not return null, but a `Passphrase` with a content of null.

Specified by:
  `getPassphraseFor` in interface `SecretKeyPassphraseProvider`
Parameters:
  `keyId` - if of the secret key
Returns:
  passphrase or null, if no passphrase record has been found.

### hasPassphrase

public boolean hasPassphrase(Long keyId)

Specified by:
  `hasPassphrase` in interface `SecretKeyPassphraseProvider`

### hasPassphraseFor

public boolean hasPassphraseFor(Long keyId)
Description copied from interface: `SecretKeyRingProtector`
Returns true, if the protector has a passphrase for the key with the given key-id.

Specified by:
  `hasPassphraseFor` in interface `SecretKeyRingProtector`
Parameters:
  `keyId` - key id
Returns:
  true if it has a passphrase, false otherwise

### getDecryptor

@Nullable public org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor getDecryptor(@Nonnull Long keyId) throws org.bouncycastle.openpgp.PGPException
Description copied from interface: `SecretKeyRingProtector`
Return a decryptor for the key of id `keyId`. This method returns null if the key is unprotected.

Specified by:
  `getDecryptor` in interface `SecretKeyRingProtector`
Parameters:
  `keyId` - id of the key
Returns:
  decryptor for the key
Throws:
  `org.bouncycastle.openpgp.PGPException` - if the decryptor cannot be created for some reason

### getEncryptor

@Nullable public org.bouncycastle.openpgp.operator.PBESecretKeyEncryptor getEncryptor(@Nonnull Long keyId) throws org.bouncycastle.openpgp.PGPException
Description copied from interface: `SecretKeyRingProtector`
Return an encryptor for the key of id `keyId`. This method returns null if the key is unprotected.

Specified by:
  `getEncryptor` in interface `SecretKeyRingProtector`
Parameters:
  `keyId` - id of the key
Returns:
  encryptor for the key
Throws:
  `org.bouncycastle.openpgp.PGPException` - if the encryptor cannot be created for some reason