OpenPGP Class

Properties   Methods   Events   Config Settings   Errors  

The OpenPGP class is used to encrypt/decrypt and sign/verify PGP messages.

Syntax

ipworksopenpgp.Openpgp

Remarks

The OpenPGP class supports encrypting/decrypting and signing/verifying OpenPGP messages in the format specified by RFC 4880.

The Encrypt, Sign, and SignAndEncrypt methods are used to create a message to be sent to your partner. You can additionally create messages bound for multiple recipients with different keys, simultaneously encrypt and compress with the most popular compression algorithms, and control other aspects such as the encrypting algorithm to use.

When a message is received, the Decrypt, VerifySignature, and DecryptAndVerifySignature methods are used to process the incoming message.

The Keys property holds the key (with private key) used to sign and decrypt.

The SignerKeys property holds the key used to verify a signature.

The RecipientKeys property holds the key used to encrypt.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

ASCIIArmor Property (OpenPGP Class)

Specifies whether to use ASCII armor to encode the output message.

Syntax

public boolean isASCIIArmor();


public void setASCIIArmor(boolean ASCIIArmor);

Default Value

False

Remarks

This property controls whether or not ASCII armoring is used on the output message. The default value is False.

AutoSelectAlgorithms Property (OpenPGP Class)

Whether to automatically select algorithms when encrypting or signing.

Syntax

public int getAutoSelectAlgorithms();


public void setAutoSelectAlgorithms(int autoSelectAlgorithms);

Default Value

0

Remarks

This property is set to the binary 'OR' of one or more options indicating which algorithms to automatically select.

When enabled automatic selection is performed by examining the perferred algorithms specified by the key.

When Encrypt is called the class will read the preferred encryption algorithm and compression method from the key specified in RecipientKeys .

If multiple keys are specified the preferred encryption algorithm and compression method from the last key is used. The EncryptingAlgorithm and CompressionMethod properties are ignored.

When Sign is called the class will read the preferred MAC algorithm and compression method from the private key specified in Keys . If multiple keys are specified the preferred MAC algorithm and compression method from the last key is used. The SigningAlgorithm and CompressionMethod properties are ignored.

The list below defines available options.

The default value is 0 which means algorithms are not automatically selected.

ClearSignature Property (OpenPGP Class)

Specifies whether or not to create a cleartext signature.

Syntax

public boolean isClearSignature();


public void setClearSignature(boolean clearSignature);

Default Value

False

Remarks

This property controls whether or not a cleartext signature is created during signing. The default value is False. When set to true a clear text signature will be created when Sign is called.

CompressionMethod Property (OpenPGP Class)

The compression algorithm used.

Syntax

public String getCompressionMethod();


public void setCompressionMethod(String compressionMethod);

Default Value

"zip"

Remarks

This property specifies which compression method is used when generating output. Possible values are:

• zip (default)
• zlib
• bzip2
• none or uncompressed

DetachedSignature Property (OpenPGP Class)

Specifies whether or not to generate a detached signature when signing a message.

Syntax

public boolean isDetachedSignature();


public void setDetachedSignature(boolean detachedSignature);

Default Value

False

Remarks

This property specifies whether or not a detached signature is created when signing a message. The default value is False.

If set to true the output will only be the signature. The data being signed will not be included in the output. If set to true ClearSignature will be ignored.

When this property is false (default) the signature is not detached. The output will contain both the signed data and the signature.

EncryptingAlgorithm Property (OpenPGP Class)

The encryption algorithm used when encrypting.

Syntax

public String getEncryptingAlgorithm();


public void setEncryptingAlgorithm(String encryptingAlgorithm);

Default Value

"AES128"

Remarks

This property specifies the encryption algorithm used when encrypting. Possible values are:

• CAST5
• 3DES or TripleDES
• AES256
• AES192
• AES128 (default)
• BLOWFISH
• TWOFISH
• IDEA

InputFile Property (OpenPGP Class)

The file to process.

Syntax

public String getInputFile();


public void setInputFile(String inputFile);

Default Value

""

Remarks

This property specifies the file to be processed. Set this property to the full or relative path to the file which will be processed.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

InputMessage Property (OpenPGP Class)

The message to process.

Syntax

public byte[] getInputMessage();


public void setInputMessage(byte[] inputMessage);

Default Value

""

Remarks

This property specifies the message to be processed. Set this property to the OpenPGP message content.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Keys Property (OpenPGP Class)

A collection of keys used for cryptographic operations.

Syntax

public KeyList getKeys();


public void setKeys(KeyList keys);

Remarks

This collection holds keys that are used for signing and decrypting. In most cases only one key will be specified, however multiple keys may be needed in some cases.

This property is not available at design time.

MessageHeaders Property (OpenPGP Class)

A collection of headers in the ASCII armored message.

Syntax

public HeaderList getMessageHeaders();


public void setMessageHeaders(HeaderList messageHeaders);

Remarks

This property holds a collection of headers specified in the message. It is only applicable when ASCIIArmor is set to true.

When generating ASCII armored output the class will include the headers specified here in addition to the standard Version header.

After decrypting or verifying a message that is ASCII armored this collection will be populated with the headers that were present in the message.

This property is not available at design time.

OutputFile Property (OpenPGP Class)

The output file.

Syntax

public String getOutputFile();


public void setOutputFile(String outputFile);

Default Value

""

Remarks

This property specifies the file to which the output will be written. This may be set to an absolute or relative path.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

OutputMessage Property (OpenPGP Class)

The output message after processing.

Syntax

public byte[] getOutputMessage();


public void setOutputMessage(byte[] outputMessage);

Default Value

""

Remarks

This property will be populated with the output from the operation if OutputFile and SetOutputStream are not set.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Overwrite Property (OpenPGP Class)

Indicates whether or not the class should overwrite files.

Syntax

public boolean isOverwrite();


public void setOverwrite(boolean overwrite);

Default Value

False

Remarks

This property indicates whether or not the class will overwrite OutputFile. If Overwrite is False, an error will be thrown whenever OutputFile exists before an operation. The default value is False.

RecipientKeys Property (OpenPGP Class)

The collection of keys belonging to the recipient of the message.

Syntax

public KeyList getRecipientKeys();


public void setRecipientKeys(KeyList recipientKeys);

Remarks

This property contains the keys of the message recipient.

Set this property before calling Encrypt or SignAndEncrypt.

This property is not available at design time.

SignerKeys Property (OpenPGP Class)

The collection of keys belonging to the signer of the message.

Syntax

public KeyList getSignerKeys();


public void setSignerKeys(KeyList signerKeys);

Remarks

This property contains the keys of the message signer.

Set this property before calling VerifySignature or DecryptAndVerifySignature.

This property is not available at design time.

SigningAlgorithm Property (OpenPGP Class)

The signature hash algorithm used when signing.

Syntax

public String getSigningAlgorithm();


public void setSigningAlgorithm(String signingAlgorithm);

Default Value

"SHA256"

Remarks

This property specifies the signature hash algorithm used when signing. Possible values are:

• SHA1
• MD5
• SHA256 (default)
• SHA384
• SHA512
• SHA224
• RIPEMD160

Config Method (Openpgp Class)

Sets or retrieves a configuration setting.

Syntax

public String config(String configurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Decrypt Method (Openpgp Class)

Decrypts the message.

Syntax

public void decrypt();

Remarks

This method decrypts the specified message.

The message will be decrypted using the keys specified in Keys. Before decryption begins the class will fire the RecipientInfo event with information about the encrypted message, including the key used to encrypt the message. Within this event you may use the available information to load the correct key into Keys.

DecryptAndVerifySignature Method (Openpgp Class)

Decrypts and verifies the signature of the message.

Syntax

public void decryptAndVerifySignature();

Remarks

This method attempts to both decrypt and verify the signature of the message. All of the properties affected by calling the Decrypt and VerifySignature methods are affected in the same manner.

This method may be used when the data is signed, encrypted, or signed and encrypted. For instance, if the data is encrypted but not signed you may still use this method and the class will perform the decryption without error.

The message will be decrypted using the keys specified in Keys. Before decryption begins the class will fire the RecipientInfo event with information about the encrypted message, including the key used to encrypt the message. Within this event you may use the available information to load the correct key into Keys.

The message will be verified using the keys specified in SignerKeys. Before verification begins the class will fire the SignatureInfo event with information about the signature including the key used to sign the message. Within this event you may use the information available to load the correct key into SignerKeys.

By default, if the signature is not valid the class throws an exception. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the VerificationStatus event should be checked to determine the result of the operation.

NOTE: This method does not attempt to check the validity of the signing key itself.

Encrypt Method (Openpgp Class)

Encrypts the message.

Syntax

public void encrypt();

Remarks

This method encrypts the specified message.

The message is encrypted with the public keys specified in RecipientKeys.

When encrypting, the following properties may be used to further configure the class:

• ASCIIArmor
• CompressionMethod
• EncryptingAlgorithm

GetRecipientInfo Method (Openpgp Class)

Gets recipient information for an encrypted message.

Syntax

public void getRecipientInfo();

Remarks

This method will fire a RecipientInfo event for every recipient key for which the message has been encrypted. The event will provide the KeyId, which can be used to identify the correct key to be used for decryption.

Interrupt Method (Openpgp Class)

Interrupt the current method.

Syntax

public void interrupt();

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

Reset Method (Openpgp Class)

Resets the class properties.

Syntax

public void reset();

Remarks

This method resets all message and key properties to their default values.

SetInputStream Method (Openpgp Class)

Sets the stream from which the class will read data to encrypt or decrypt.

Syntax

public void setInputStream(java.io.InputStream inputStream);

Remarks

This method sets the stream from which the class will read data to encrypt or decrypt. If an input stream is set before the class attempts to encode or decode an OpenPGP message, the data is read from the input stream instead of from the InputFile or InputMessage properties.

Encrypt and/or Sign

You can call this method to set the input stream that you would like to sign and/or encrypt. Then call Sign, Encrypt, or SignAndEncrypt to sign and/or encrypt the message. The appropriate ASCII Armor headers will be generated in MessageHeaders.

Decrypt and/or Verify

You can call this method to specify a valid input stream that contains the signed and/or encrypted data you would like to verify or decrypt. Then call VerifySignature, Decrypt, or DecryptAndVerifySignature to verify and/or decrypt the message.

The content of the stream will be read from the current position all the way to the end and no bytes will be skipped.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

SetOutputStream Method (Openpgp Class)

The stream to which the class will write the fully encrypted or decrypted OpenPGP data.

Syntax

public void setOutputStream(java.io.OutputStream outputStream);

Remarks

This method sets the stream to which the class will write the fully encrypted or decrypted OpenPGP data. If an output stream is set before the class attempts to encode or decode an OpenPGP message, the class will write the data to the output stream instead of populating OutputMessage or writing to OutputFile.

Sign and/or Encrypt

To sign and/or encrypt a message to an output stream, you must first populate the Message property with the data you would like to sign and/or encrypt. Next, this method must be called with a valid output stream for which the class may write the signed or encrypted data. Then call Sign, Encrypt, or SignAndEncrypt to sign and/or encrypt the message. The appropriate ASCII Armor headers will be generated in MessageHeaders.

Decrypt and/or Verify

If you would like to decrypt a message or verify its signature and write the resulting message to an output stream, you should set the Message property to the signed and/or encrypted message you would like to verify or decrypt. Next, you must call this method to specify a valid stream for the component to write the data to. Then call VerifySignature, Decrypt, or DecryptAndVerifySignature to verify and/or decrypt the message.

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

• SetInputStream
• InputFile
• InputMessage

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• SetOutputStream
• OutputFile
• OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Sign Method (Openpgp Class)

Signs the message.

Syntax

public void sign();

Remarks

This method signs the specified message.

The message is signed with the private key specified in Keys .

When signing, the following properties may be used to further configure the class:

• ASCIIArmor
• ClearSignature
• DetachedSignature
• SigningAlgorithm

SignAndEncrypt Method (Openpgp Class)

Signs and encrypts the current message.

Syntax

public void signAndEncrypt();

Remarks

This method signs and encrypts the specified message.

The message is encrypted with the public keys specified in RecipientKeys and signed with the private key specified in Keys .

When encrypting, the following properties may be used to further configure the class:

• ASCIIArmor
• CompressionMethod
• EncryptingAlgorithm

When signing, the following properties may be used to further configure the class:

• ASCIIArmor
• ClearSignature
• DetachedSignature
• SigningAlgorithm

VerifySignature Method (Openpgp Class)

Verifies the signature of the current message.

Syntax

public void verifySignature();

Remarks

This method verifies the signature of the message.

The message will be verified using the keys specified in SignerKeys. Before verification begins the class will fire the SignatureInfo event with information about the signature including the key used to sign the message. Within this event you may use the information available to load the correct key into SignerKeys.

By default, if the signature is not valid the class throws an exception. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the VerificationStatus event should be checked to determine the result of the operation.

Error Event (Openpgp Class)

Information about errors during data delivery.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void error(OpenpgpErrorEvent e) {}
  ...
}

public class OpenpgpErrorEvent {
  public int errorCode;
  public String description;
}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

KeyPassphrase Event (Openpgp Class)

Fired if the passphrase of current key is incorrect or empty.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void keyPassphrase(OpenpgpKeyPassphraseEvent e) {}
  ...
}

public class OpenpgpKeyPassphraseEvent {
  public String userId;
  public String keyId;
  public String passphrase;
}

Remarks

This event fires when the passphrase for the key is required. The passphrase must be specified before operations requiring the secret key are attempted. The passphrase may be supplied by setting the Passphrase parameter in this event, or by specifying the Passphrase field before attempting the operation.

The passphrase is required when using the following methods in KeyMgr:

• AddUserId
• SignUserId
• ChangeExpirationDate
• ChangePassphrase

When using the OpenPGP class, or an email-based class, the following methods require a passphrase for the key:

• Decrypt
• Sign
• SignAndEncrypt

Progress Event (Openpgp Class)

Fired as progress is made.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void progress(OpenpgpProgressEvent e) {}
  ...
}

public class OpenpgpProgressEvent {
  public long bytesProcessed;
  public int percentProcessed;
  public int operation;
  public boolean isEOF;
}

Remarks

This event is fired automatically as data is processed by the class.

The PercentProcessed parameter indicates the current status of the operation.

The BytesProcessed parameter holds the total number of bytes processed so far.

The Operation parameter is only applicable when either ReadFromProgressEvent or WriteToProgressEvent is set to True. This parameter defines whether a Read or Write operation is required. If the configuration settings are not set this parameter will always return 0. Possible values are:

The IsEOF parameter is only applicable when either ReadFromProgressEvent or WriteToProgressEvent is set to True. This parameter defines whether the Read or Write operation is complete. When the Operation is Read (1) this parameter must be set to indicate that all data has been supplied to the class. When the Operation is Write (2) this value may be queried to determine when all data has been processed.

RecipientInfo Event (Openpgp Class)

Fired for each recipient key of the encrypted message.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void recipientInfo(OpenpgpRecipientInfoEvent e) {}
  ...
}

public class OpenpgpRecipientInfoEvent {
  public String keyId;
  public String publicKeyAlgorithm;
}

Remarks

This event fires when the Decrypt or DecryptAndVerifySignature method is called.

KeyId is the Id of the key used to encrypt the message. If a subkey was used to encrypt the message this will be the Id of that subkey. It is the hex-encoded, 4- or 8-byte Id of the key. It is the same as the last 4 or 8 bytes of the fingerprint. For instance:

BF52A0AB

SignatureInfo Event (Openpgp Class)

Fired during verification of the signed message.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void signatureInfo(OpenpgpSignatureInfoEvent e) {}
  ...
}

public class OpenpgpSignatureInfoEvent {
  public String keyId;
  public String signingAlgorithm;
  public String publicKeyAlgorithm;
}

Remarks

This event fires when the VerifySignature or DecryptAndVerifySignature method is called. It provides information about the signature of the message.

KeyId is the Id of the key used to sign the message. If a subkey was used to sign the message this will be the Id of that subkey. It is the hex-encoded, 4- or 8-byte Id of the key. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance:

BF52A0AB

SigningAlgorithm describes the hash algorithm used when the message was originally signed. This value is applicable only to the message signature, not the key used to sign the message. Possible values are:

• SHA1
• SHA256
• SHA384
• SHA512
• SHA224
• MD5

PublicKeyAlgorithm is the algorithm of the public key used to sign the message. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA

Status Event (Openpgp Class)

Shows the progress of the operation.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void status(OpenpgpStatusEvent e) {}
  ...
}

public class OpenpgpStatusEvent {
  public String message;
}

Remarks

The event is fired for informational and logging purposes only. It may be used to track the progress of an operation.

The level of detail is controlled by the LogLevel setting.

VerificationStatus Event (Openpgp Class)

Fired after verification of the signed message.

Syntax

public class DefaultOpenpgpEventListener implements OpenpgpEventListener {
  ...
  public void verificationStatus(OpenpgpVerificationStatusEvent e) {}
  ...
}

public class OpenpgpVerificationStatusEvent {
  public String keyId;
  public int status;
}

Remarks

This event fires when VerifySignature or DecryptAndVerifySignature is called. It provides information about the result.

KeyId is the Id of the key used to sign the message. It is the hex-encoded, 4-or 8-byte Id of the key. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance:

BF52A0AB

Status holds the result of the operation. Possible values are:

Header Type

This is an HTTP header as it is received from the server.

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a Field, and its corresponding Value.

Fields

Constructors

public Header();

public Header( field,  value);

Key Type

The OpenPGP key being used.

Remarks

This type describes the current key. The key may be a public or secret key. The fields are used to identify or select the key.

Fields

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

89C9D7B1

FirstName LastName (Comment) <Email>

Constructors

public Key( keyPath);

Reads the OpenPGP public key from the specified KeyPath . If multiple keys are present only the first one is used.

public Key( keyData);

Reads the OpenPGP key from the specified KeyData . Both binary-formatted and ASCII-armored data are accepted.

public Key( keyPath,  userId);

Searches the KeyPath for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used.

public Key( keyPath,  secretKeyringFile,  publicKeyringFile,  userId);

Searches the KeyPath for the specified SecretKeyRingFile and PublicKeyringFile . If UserId is set to "*" the first key will be used.

public Key( keyData,  userId);

Searches the KeyData for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used.

Config Settings (Openpgp Class)

OpenPGP Config Settings

89011C04000102000605025100459B000A0910E2...

Base Config Settings

Trappable Errors (Openpgp Class)

OpenPGP Errors