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(java.util.Map<java.lang.Long,Passphrase> passphraseMap)	Use the provided map of key-ids and passphrases to unlock keys.
org.bouncycastle.openpgp.operator.PBESecretKeyDecryptor	getDecryptor(java.lang.Long keyId)	Return a decryptor for the key of id keyId.
org.bouncycastle.openpgp.operator.PBESecretKeyEncryptor	getEncryptor(java.lang.Long keyId)	Return an encryptor for the key of id keyId.
boolean	hasPassphraseFor(java.lang.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 Detail

hasPassphraseFor

boolean hasPassphraseFor(java.lang.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(java.lang.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(java.lang.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
                                                java.util.Map<java.lang.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