Package org.pgpainless.key.protection

# Interface SecretKeyRingProtector

All Known Implementing Classes:
  `BaseSecretKeyRingProtector`, `CachingSecretKeyRingProtector`, `PasswordBasedSecretKeyRingProtector`, `UnprotectedKeysProtector`

public interface SecretKeyRingProtector
Task of the `SecretKeyRingProtector` is to map encryptor/decryptor objects to key-ids. `PBESecretKeyEncryptors`/`PBESecretKeyDecryptors` are used to encrypt/decrypt secret keys using a passphrase. While it is easy to create an implementation of this interface that fits your needs, there are a bunch of implementations ready for use.

## Method Summary

Modifier and Type
Method
Description
`static CachingSecretKeyRingProtector`
`defaultSecretKeyRingProtector(SecretKeyPassphraseProvider missingPassphraseCallback)`
Return a protector for secret keys.
`static SecretKeyRingProtector`
`fromPassphraseMap(Map<Long,Passphrase> passphraseMap)`
Use the provided map of key-ids and passphrases to unlock keys.
`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`.
`boolean`
`hasPassphraseFor(Long keyId)`
Returns true, if the protector has a passphrase for the key with the given key-id.
`static SecretKeyRingProtector`
`unlockAllKeysWith(Passphrase passphrase, org.bouncycastle.openpgp.PGPSecretKeyRing keys)`
Deprecated.
use `unlockEachKeyWith(Passphrase, PGPSecretKeyRing)` instead.
`static SecretKeyRingProtector`
`unlockAnyKeyWith(Passphrase passphrase)`
Use the provided passphrase to unlock any key.
`static SecretKeyRingProtector`
`unlockEachKeyWith(Passphrase passphrase, org.bouncycastle.openpgp.PGPSecretKeyRing keys)`
Use the provided passphrase to lock/unlock all keys in the provided key ring.
`static SecretKeyRingProtector`
`unlockSingleKeyWith(Passphrase passphrase, long keyId)`
`static SecretKeyRingProtector`
`unlockSingleKeyWith(Passphrase passphrase, org.bouncycastle.openpgp.PGPSecretKey key)`
Use the provided passphrase to lock/unlock only the provided (sub-)key.
`static SecretKeyRingProtector`
`unprotectedKeys()`
Protector for unprotected keys.

## Method Details

### hasPassphraseFor

boolean hasPassphraseFor(Long keyId)
Returns true, if the protector has a passphrase for the key with the given key-id.

Parameters:
  `keyId` - key id
Returns:
  true if it has a passphrase, false otherwise

### getDecryptor

@Nullable org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor getDecryptor(Long keyId) throws org.bouncycastle.openpgp.PGPException
Return a decryptor for the key of id `keyId`. This method returns null if the key is unprotected.

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 org.bouncycastle.openpgp.operator.PBESecretKeyEncryptor getEncryptor(Long keyId) throws org.bouncycastle.openpgp.PGPException
Return an encryptor for the key of id `keyId`. This method returns null if the key is unprotected.

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

### defaultSecretKeyRingProtector

static CachingSecretKeyRingProtector defaultSecretKeyRingProtector(SecretKeyPassphraseProvider missingPassphraseCallback)
Return a protector for secret keys. The protector maintains an in-memory cache of passphrases and can be extended with new passphrases at runtime. See `CachingSecretKeyRingProtector` for how to memorize/forget additional passphrases during runtime.

Parameters:
  `missingPassphraseCallback` - callback that is used to provide missing passphrases.
Returns:
  caching secret key protector

### unlockAllKeysWith

@Deprecated static SecretKeyRingProtector unlockAllKeysWith(@Nonnull Passphrase passphrase, @Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing keys)
Deprecated.
use `unlockEachKeyWith(Passphrase, PGPSecretKeyRing)` instead. TODO: Remove in 1.2.X
Use the provided passphrase to lock/unlock all keys in the provided key ring. This protector will use the provided passphrase to lock/unlock all subkeys present in the provided keys object. For other keys that are not present in the ring, it will return null.

Parameters:
  `passphrase` - passphrase
  `keys` - key ring
Returns:
  protector

### unlockEachKeyWith

static SecretKeyRingProtector unlockEachKeyWith(@Nonnull Passphrase passphrase, @Nonnull org.bouncycastle.openpgp.PGPSecretKeyRing keys)
Use the provided passphrase to lock/unlock all keys in the provided key ring. This protector will use the provided passphrase to lock/unlock all subkeys present in the provided keys object. For other keys that are not present in the ring, it will return null.

Parameters:
  `passphrase` - passphrase
  `keys` - key ring
Returns:
  protector

### unlockAnyKeyWith

static SecretKeyRingProtector unlockAnyKeyWith(@Nonnull Passphrase passphrase)
Use the provided passphrase to unlock any key.

Parameters:
  `passphrase` - passphrase
Returns:
  protector

### unlockSingleKeyWith

static SecretKeyRingProtector unlockSingleKeyWith(@Nonnull Passphrase passphrase, @Nonnull org.bouncycastle.openpgp.PGPSecretKey key)
Use the provided passphrase to lock/unlock only the provided (sub-)key. This protector will only return a non-null encryptor/decryptor based on the provided passphrase if `getEncryptor(Long)`/`getDecryptor(Long)` is getting called with the key-id of the provided key. Otherwise, this protector will always return null.

Parameters:
  `passphrase` - passphrase
  `key` - key to lock/unlock
Returns:
  protector

### unlockSingleKeyWith

static SecretKeyRingProtector unlockSingleKeyWith(@Nonnull Passphrase passphrase, long keyId)

### unprotectedKeys

static SecretKeyRingProtector unprotectedKeys()
Protector for unprotected keys. This protector returns null for all `getEncryptor(Long)`/`getDecryptor(Long)` calls, no matter what the key-id is. As a consequence, this protector can only "unlock" keys which are not protected using a passphrase, and it will leave keys unprotected, should it be used to "protect" a key (e.g. in `SecretKeyRingEditorInterface.changePassphraseFromOldPassphrase(Passphrase)`).

Returns:
  protector

### fromPassphraseMap

static SecretKeyRingProtector fromPassphraseMap(@Nonnull Map<Long,Passphrase> passphraseMap)
Use the provided map of key-ids and passphrases to unlock keys.

Parameters:
  `passphraseMap` - map of key ids and their respective passphrases
Returns:
  protector