org.c02e.jpgpj

Class Decryptor

java.lang.Object

org.c02e.jpgpj.Decryptor

All Implemented Interfaces:

java.lang.Cloneable

public class Decryptor
extends java.lang.Object
implements java.lang.Cloneable

Decrypts and verifies PGP messages using the decryption and verification Keys supplied on this object's Ring.

To turn off verification, setVerificationRequired(boolean) to false. To decrypt a message encrypted with a passphrase (instead of, or in addition to, a public-key pair), use setSymmetricPassphrase(java.lang.String) to supply the passphrase.

Here's an example of Bob decrypting and verifying an encrypted file that was signed by Alice:

 new Decryptor(
     new Key(new File("path/to/my/keys/alice-pub.gpg")),
     new Key(new File("path/to/my/keys/bob-sec.gpg"), "b0bru1z!")
 ).decrypt(
     new File("path/to/ciphertext.txt.gpg"),
     new File("path/back-to/plaintext.txt")
 );
 

This is equivalent to the following `gpg` command (where Bob has a `bob` secret key and an `alice` public key on his keyring, and enters "b0bru1z!" when prompted for his passphrase):

 gpg --decrypt --output path/back-to/plaintext.txt path/to/ciphertext.txt.gpg
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Decryptor.VerificationType Type of signature verification done by decryptor.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_COPY_FILE_BUFFER_SIZE
static boolean	DEFAULT_LOGGING_ENABLED
static int	DEFAULT_MAX_FILE_BUFFER_SIZE
static boolean	DEFAULT_VERIFICATION_REQUIRED
static Decryptor.VerificationType	DEFAULT_VERIFICATION_TYPE

Constructor Summary

Constructors

Constructor and Description
Decryptor() Constructs a decryptor with an empty key ring.
Decryptor(Key... keys) Constructs a decryptor with the specified keys.
Decryptor(Ring ring) Constructs a decryptor with the specified key ring.

Method Summary

Modifier and Type	Method and Description
void	clearSecrets() Zeroes-out the cached passphrase for all keys, and releases the extracted private key material for garbage collection.
Decryptor	clone()
FileMetadata	decrypt(java.io.File ciphertext, java.io.File plaintext) Decrypts the first specified file to the output location specified by the second file, and (if isVerificationRequired()) verifies its signatures.
FileMetadata	decrypt(java.io.InputStream ciphertext, java.io.OutputStream plaintext) Decrypts the specified PGP message into the specified output stream, and (if isVerificationRequired()) verifies the message signatures.
FileMetadata	decrypt(java.nio.file.Path ciphertext, java.nio.file.Path plaintext) Decrypts the first specified file to the output location specified by the second file, and (if isVerificationRequired()) verifies its signatures.
DecryptionResult	decryptWithFullDetails(java.io.InputStream ciphertext, java.io.OutputStream plaintext) Decrypts the specified PGP message into the specified output stream, including the armored headers (if stream was armored and contained any such headers).
byte[]	getCopyBuffer() Internal buffer for copying decrypted plaintext into the output stream.
int	getCopyFileBufferSize()
int	getMaxFileBufferSize()
Ring	getRing()
java.lang.String	getSymmetricPassphrase()
char[]	getSymmetricPassphraseChars()
Decryptor.VerificationType	getVerificationType() Type of signature verification.
boolean	isLoggingEnabled()
boolean	isVerificationRequired()
void	setCopyFileBufferSize(int copyFileBufferSize)
void	setLoggingEnabled(boolean enabled)
void	setMaxFileBufferSize(int maxFileBufferSize) Decryptor will choose the most appropriate read/write buffer size for each file.
void	setRing(Ring x)
void	setSymmetricPassphrase(java.lang.String x)
void	setSymmetricPassphraseChars(char[] x)
void	setVerificationRequired(boolean x)
void	setVerificationType(Decryptor.VerificationType x) Type of signature verification.
Decryptor	withCopyFileBufferSize(int copyFileBufferSize)
Decryptor	withLoggingEnabled(boolean enabled)
Decryptor	withMaxFileBufferSize(int maxFileBufferSize)
Decryptor	withRing(Ring x)
Decryptor	withSymmetricPassphrase(java.lang.String x)
Decryptor	withSymmetricPassphraseChars(char[] x)
Decryptor	withVerificationRequired(boolean x)
Decryptor	withVerificationType(Decryptor.VerificationType x) Type of signature verification.
java.io.InputStream	wrapSourceInputStream(java.io.InputStream sourceStream, long inputSize)
java.io.OutputStream	wrapTargetOutputStream(java.io.OutputStream targetStream, long inputSize)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MAX_FILE_BUFFER_SIZE

public static final int DEFAULT_MAX_FILE_BUFFER_SIZE

See Also:

Constant Field Values

DEFAULT_VERIFICATION_TYPE

public static final Decryptor.VerificationType DEFAULT_VERIFICATION_TYPE

DEFAULT_VERIFICATION_REQUIRED

public static final boolean DEFAULT_VERIFICATION_REQUIRED

See Also:

Constant Field Values

DEFAULT_COPY_FILE_BUFFER_SIZE

public static final int DEFAULT_COPY_FILE_BUFFER_SIZE

See Also:

Constant Field Values

DEFAULT_LOGGING_ENABLED

public static final boolean DEFAULT_LOGGING_ENABLED

See Also:

Constant Field Values

Constructor Detail

Decryptor

public Decryptor()

Constructs a decryptor with an empty key ring.

Decryptor

public Decryptor(Ring ring)

Constructs a decryptor with the specified key ring.

Decryptor

public Decryptor(Key... keys)

Constructs a decryptor with the specified keys.

Method Detail

getVerificationType

public Decryptor.VerificationType getVerificationType()

Type of signature verification. Defaults to Decryptor.VerificationType.Required.

setVerificationType

public void setVerificationType(Decryptor.VerificationType x)

Type of signature verification.

withVerificationType

public Decryptor withVerificationType(Decryptor.VerificationType x)

Type of signature verification.

isVerificationRequired

public boolean isVerificationRequired()

Returns:

true to require messages be signed with at least one key from ring. Defaults to true.

setVerificationRequired

public void setVerificationRequired(boolean x)

Parameters:

x - true to require messages be signed with at least one key from ring. Defaults to true.

See Also:

DEFAULT_VERIFICATION_REQUIRED

withVerificationRequired

public Decryptor withVerificationRequired(boolean x)

See Also:

setVerificationRequired(boolean)

getSymmetricPassphraseChars

public char[] getSymmetricPassphraseChars()

Returns:

Passphrase to use to decrypt with a symmetric key; or empty char[]. Note that this char[] itself (and not a copy) will be cached and used until clearSecrets() is called (or setSymmetricPassphraseChars(char[]) is called again with a different passphrase, and then the char[] will be zeroed.

setSymmetricPassphraseChars

public void setSymmetricPassphraseChars(char[] x)

Parameters:

x - Passphrase to use to decrypt with a symmetric key; or empty char[]. Note that this char[] itself (and not a copy) will be cached and used until clearSecrets() is called (or setSymmetricPassphraseChars(char[]) is called again with a different passphrase, and then the char[] will be zeroed.

withSymmetricPassphraseChars

public Decryptor withSymmetricPassphraseChars(char[] x)

See Also:

setSymmetricPassphraseChars(char[])

getSymmetricPassphrase

public java.lang.String getSymmetricPassphrase()

Returns:

Passphrase to use to decrypt with a symmetric key; or empty string. Prefer getSymmetricPassphraseChars() to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.

See Also:

getSymmetricPassphraseChars()

setSymmetricPassphrase

public void setSymmetricPassphrase(java.lang.String x)

Parameters:

x - Passphrase to use to decrypt with a symmetric key; or empty string. Prefer setSymmetricPassphraseChars(char[]) to avoid creating extra copies of the passphrase in memory that cannot be cleaned up.

See Also:

setSymmetricPassphraseChars(char[])

withSymmetricPassphrase

public Decryptor withSymmetricPassphrase(java.lang.String x)

See Also:

setSymmetricPassphrase(String)

getMaxFileBufferSize

public int getMaxFileBufferSize()

setMaxFileBufferSize

public void setMaxFileBufferSize(int maxFileBufferSize)

Decryptor will choose the most appropriate read/write buffer size for each file. You can set the maximum value here. Defaults to 1MB.

Parameters:

maxFileBufferSize - The read/write buffer size

See Also:

DEFAULT_MAX_FILE_BUFFER_SIZE

withMaxFileBufferSize

public Decryptor withMaxFileBufferSize(int maxFileBufferSize)

See Also:

setMaxFileBufferSize(int)

getCopyFileBufferSize

public int getCopyFileBufferSize()

Returns:

Internal buffer size used to copy data from input ciphertext stream to output plaintext stream internally

See Also:

DEFAULT_COPY_FILE_BUFFER_SIZE, getCopyBuffer()

setCopyFileBufferSize

public void setCopyFileBufferSize(int copyFileBufferSize)

Parameters:

copyFileBufferSize - Internal buffer size used to copy data from input ciphertext stream to output plaintext stream internally

See Also:

DEFAULT_COPY_FILE_BUFFER_SIZE, getCopyBuffer()

withCopyFileBufferSize

public Decryptor withCopyFileBufferSize(int copyFileBufferSize)

See Also:

setCopyFileBufferSize(int)

getRing

public Ring getRing()

Returns:

Keys Ring to use for decryption and verification.

setRing

public void setRing(Ring x)

Parameters:

x - Keys Ring to use for decryption and verification.

withRing

public Decryptor withRing(Ring x)

See Also:

setRing(Ring)

isLoggingEnabled

public boolean isLoggingEnabled()

Returns:

true if logging a brief summary of the execution every time decryption is executed (e.g. file name/path, size, compression type, etc.). Note: errors/warnings logging are not affected by this setting

setLoggingEnabled

public void setLoggingEnabled(boolean enabled)

Parameters:

enabled - true if should log a brief summary of the execution every time decryption is executed (e.g. file name/path, size, compression type, etc.). Note: errors/warnings logging are not affected by this setting

withLoggingEnabled

public Decryptor withLoggingEnabled(boolean enabled)

See Also:

setLoggingEnabled(boolean)

clearSecrets

public void clearSecrets()

Zeroes-out the cached passphrase for all keys, and releases the extracted private key material for garbage collection.

decrypt

public FileMetadata decrypt(java.io.File ciphertext,
                            java.io.File plaintext)
                     throws java.io.IOException,
                            org.bouncycastle.openpgp.PGPException

Decrypts the first specified file to the output location specified by the second file, and (if isVerificationRequired()) verifies its signatures. If a file already exists in the output file's location, it will be deleted. If an exception occurs during decryption, the output file will be deleted.

Parameters:

ciphertext - File containing a PGP message, in binary or ASCII Armor format.

plaintext - File into which to decrypt the message.

Returns:

Metadata of original file, and the list of keys that signed the message with a verified signature. The original file metadata values are optional, and may be missing or incorrect.

Throws:

java.io.IOException - if an IO error occurs reading from or writing to the underlying input or output streams.

org.bouncycastle.openpgp.PGPException - if the PGP message is not formatted correctly.

PassphraseException - if an incorrect passphrase was supplied for one of the decryption keys, or as the getSymmetricPassphrase().

DecryptionException - if the message was not encrypted for any of the keys supplied for decryption.

VerificationException - if isVerificationRequired() and the message was not signed by any of the keys supplied for verification.

decrypt

public FileMetadata decrypt(java.nio.file.Path ciphertext,
                            java.nio.file.Path plaintext)
                     throws java.io.IOException,
                            org.bouncycastle.openpgp.PGPException

Decrypts the first specified file to the output location specified by the second file, and (if isVerificationRequired()) verifies its signatures. If a file already exists in the output file's location, it will be deleted. If an exception occurs during decryption, the output file will be deleted.

Parameters:

ciphertext - Path to file containing a PGP message, in binary or ASCII Armor format.

plaintext - Path of the file into which to decrypt the message.

Returns:

Metadata of original file, and the list of keys that signed the message with a verified signature. The original file metadata values are optional, and may be missing or incorrect.

Throws:

java.io.IOException - if an IO error occurs reading from or writing to the underlying input or output streams.

org.bouncycastle.openpgp.PGPException - if the PGP message is not formatted correctly.

PassphraseException - if an incorrect passphrase was supplied for one of the decryption keys, or as the getSymmetricPassphrase().

DecryptionException - if the message was not encrypted for any of the keys supplied for decryption.

VerificationException - if isVerificationRequired() and the message was not signed by any of the keys supplied for verification.

wrapSourceInputStream

public java.io.InputStream wrapSourceInputStream(java.io.InputStream sourceStream,
                                                 long inputSize)
                                          throws java.io.IOException

Parameters:

sourceStream - Original source (ciphertext) InputStream

inputSize - Expected input (ciphertext) size

Returns:

A wrapper buffered stream optimized for the input size according to the current encryptor settings

Throws:

java.io.IOException - If failed to generate the wrapper

wrapTargetOutputStream

public java.io.OutputStream wrapTargetOutputStream(java.io.OutputStream targetStream,
                                                   long inputSize)
                                            throws java.io.IOException

Parameters:

targetStream - Original target (plaintext) OutputStream

inputSize - Expected input (ciphertext) size

Returns:

A wrapper buffered stream optimized for the input size according to the current encryptor settings

Throws:

java.io.IOException - If failed to generate the wrapper

decrypt

public FileMetadata decrypt(java.io.InputStream ciphertext,
                            java.io.OutputStream plaintext)
                     throws java.io.IOException,
                            org.bouncycastle.openpgp.PGPException

Decrypts the specified PGP message into the specified output stream, and (if isVerificationRequired()) verifies the message signatures. Does not close or flush the streams.

Note that the full decrypted content will be written to the output stream before the message is verified, so you may want to buffer the content and not write it to its final destination until this method returns.

Parameters:

ciphertext - PGP message, in binary or ASCII Armor format.

plaintext - Decrypted content.

Returns:

Metadata of original file, and the list of keys that signed the message with a verified signature. The original file metadata values are optional, and may be missing or incorrect.

Throws:

java.io.IOException - if an IO error occurs reading from or writing to the underlying input or output streams.

org.bouncycastle.openpgp.PGPException - if the PGP message is not formatted correctly.

PassphraseException - if an incorrect passphrase was supplied for one of the decryption keys, or as the getSymmetricPassphrase().

DecryptionException - if the message was not encrypted for any of the keys supplied for decryption.

VerificationException - if isVerificationRequired() and the message was not signed by any of the keys supplied for verification.

See Also:

decryptWithFullDetails

decryptWithFullDetails

public DecryptionResult decryptWithFullDetails(java.io.InputStream ciphertext,
                                               java.io.OutputStream plaintext)
                                        throws java.io.IOException,
                                               org.bouncycastle.openpgp.PGPException

Decrypts the specified PGP message into the specified output stream, including the armored headers (if stream was armored and contained any such headers). If isVerificationRequired() also verifies the message signatures. Note: does not close or flush the streams.

Parameters:

ciphertext - PGP message, in binary or ASCII Armor format.

plaintext - Decrypted content target OutputStream

Returns:

The DecryptionResult containing all relevant information that could be extracted from the encrypted data - including metadata, armored headers (if any), etc...

Throws:

java.io.IOException - if an IO error occurs reading from or writing to the underlying input or output streams.

org.bouncycastle.openpgp.PGPException - if the PGP message is not formatted correctly.

PassphraseException - if an incorrect passphrase was supplied for one of the decryption keys, or as the getSymmetricPassphrase().

DecryptionException - if the message was not encrypted for any of the keys supplied for decryption.

VerificationException - if isVerificationRequired() and the message was not signed by any of the keys supplied for verification.

getCopyBuffer

public byte[] getCopyBuffer()

Internal buffer for copying decrypted plaintext into the output stream.

clone

public Decryptor clone()

Overrides:

clone in class java.lang.Object