Configuring iSM Components for the iWay Pretty Good Privacy (PGP) Extension

This section describes how to configure the following iSM Components for the iWay Pretty Good Privacy (PGP) Extension:

Configuring the PGP Encryption and Signature Service

Syntax:

com.ibi.agents.PGPEncrypt

Description:

This service is used to encrypt and/or sign a document using Pretty Good Privacy. PGP is specified in RFC4880. This section assumes you are familiar with PGP.

PGP encrypts using a symmetric algorithm using a new session key for each message. The session key is itself encrypted and bundled with the cipher text. The session key can be encrypted in one of two methods: passphrase or key pair. The passphrase method hashes a long password to produce the key encryption key. The key pair method uses the public key of the recipient as the key encryption key. When using the key pair method, the recipient public key must be stored in a public key ring to be retrieved.

PGP signs messages using the private key of the signer. The private key must be stored in a secret key ring to be retrieved.

PGP performs the operations in this order: the clear text message is signed first, the result is compressed and finally it is encrypted. It is possible to skip any of these steps. When none of the operations are selected, the result is still a binary PGP message made up of a literal data packet.

Parameters:

The following tables describe parameters for the PGP Encryption and Signature Service. Each table is followed by a discussion of the specific parameter group.

General Parameters
Parameter Name
Description
Armor
Determines whether the binary message will be armored for transfer in ASCII.
Literal Filename
The file name to appear in the Literal Data Packet. The receiving program may use this name when storing the data to disk. The special value _CONSOLE means the data is unusually sensitive.

General Parameters
Armor	Determines whether the binary message will be armored for transfer in ASCII.
Literal Filename	The file name to appear in the Literal Data Packet. The receiving program may use this name when storing the data to disk. The special value _CONSOLE means the data is unusually sensitive.

The result of processing a document with PGP is a binary message. PGP defines a format called armoring that encodes the binary information in ASCII similar to Base64. The message is not more secure since it encodes exactly the same binary information. This format is useful to protect the data during transport when the media could inadvertently alter it, for example in the body of an email message.

PGP wraps the original message in a Literal Data Packet. This packet contains an optional field that can hold a filename. This can be used by the recipient as a hint when storing the data to disk. The special value _CONSOLE means the data is for your eyes only and should not be permanently saved. This is just a convention and PGP does not enforce it.

Signature Parameters
Parameter Name
Description
Sign
Whether to sign the data in the PGP message.
Signature Hash Algorithm
Algorithm to use for the signature digest.
Secret Key Ring
Location of the secret key ring containing the signature key.
Signature Key User ID
The User ID of the private key used for signing. The format can be =name for the exact User ID, user@host to match only the email address, or <user@host> optionally surrounded by ignored comments to match only the value within angle brackets against the email address. This parameter also determines which User ID(s) will be listed in Signer's User ID subpackets.
Signature Key ID
The Key ID of the private key used for signing. The format can be 8 hex digits for the short key ID, 16 hex digits for the long key ID, or 40 hex digits for the fingerprint. Spaces are allowed, but are not counted in the length. This parameter can be used in place or together with the Signature Key User ID to select a more specific key.
Signature Key Passphrase
Case-sensitive passphrase to unlock the Signature Private Key.
Signature Expiration
The number of seconds after the signature creation time that the signature expires. The format is:
[xxh][xxm]xx[s]
If absent or has a value of zero, the signature never expires.

Signature Parameters
Sign	Whether to sign the data in the PGP message.
Signature Hash Algorithm	Algorithm to use for the signature digest.
Secret Key Ring	Location of the secret key ring containing the signature key.
Signature Key User ID	The User ID of the private key used for signing. The format can be =name for the exact User ID, user@host to match only the email address, or <user@host> optionally surrounded by ignored comments to match only the value within angle brackets against the email address. This parameter also determines which User ID(s) will be listed in Signer's User ID subpackets.
Signature Key ID	The Key ID of the private key used for signing. The format can be 8 hex digits for the short key ID, 16 hex digits for the long key ID, or 40 hex digits for the fingerprint. Spaces are allowed, but are not counted in the length. This parameter can be used in place or together with the Signature Key User ID to select a more specific key.
Signature Key Passphrase	Case-sensitive passphrase to unlock the Signature Private Key.
Signature Expiration	The number of seconds after the signature creation time that the signature expires. The format is: [xxh][xxm]xx[s] If absent or has a value of zero, the signature never expires.

The Sign parameter determines whether the clear text document will be signed. When the document is unsigned, the remaining parameters of this group are ignored.

The Signature Hash Algorithm parameter specifies the algorithm used to compute the hash. The signature algorithm itself is determined by the type of the signature key. For example, an RSA signature key will create an RSA signature, similarly, a DSA signature key will produce a DSA signature.

The Signature Key User ID and the Signature Key ID specify which signature key will be retrieved from the Secret Key Ring. The User ID is possibly ambiguous but is convenient for humans. The Key ID should be used when the signer key must be determined more precisely. Both parameters are optional. The signer key must satisfy both criteria when both parameters are used. When both parameters are absent, the default signature key is chosen. The signer key must not be revoked and it must not be an encryption only key.

The Signature Key Passphrase is required to unlock the signature private key. This is because the private key is encrypted within the secret key ring.

The Signature Expiration is optional. It determines how long the signature will remain valid. The format is:

[xxh][xxm]xx[s]

For example, 1h30m means the signature will be valid for 90 minutes. If the value is absent or has a value of zero, the signature never expires.

Compression Parameters
Parameter Name
Description
Compress
Whether to compress the data in the PGP message.
Compression Algorithm
Algorithm to use to compress the data in the PGP message.

Compression Parameters
Compress	Whether to compress the data in the PGP message.
Compression Algorithm	Algorithm to use to compress the data in the PGP message.

The Compress parameter determines whether the data will be compressed. This will be the signed data when signature is on, or the clear text message when unsigned. PGP almost always compresses the message. It might be necessary to turn off compression to work around a problem with the software of a partner. The Compression Algorithm parameter specifies which algorithm will be used to compress the message. The default is ZIP.

Encryption Parameters
Parameter Name
Description
Encrypt
Whether to encrypt the data in the PGP message.
Symmetric Algorithm
Symmetric algorithm to be used for encryption.
Encryption Method
Determines how the session key is encrypted, use Passphrase for Password-Based Encryption (PBE), use Keypair to encrypt with a public key.
Encryption Passphrase
Case sensitive passphrase when using the Passphrase encryption method. The passphrase will be used to generate a key encryption key to encrypt the session key.
Public Key Ring
Location of the public key ring containing the encryption public key when using the Keypair encryption method.
Encryption Key User ID
User ID of the recipient public key when using the Keypair encryption method. The format can be =name for the exact User ID, user@host to match only the email address, or <user@host> optionally surrounded by ignored comments to match only the value within angle brackets against the email address. For backwards compatibility, this parameter defaults to the value of the Encryption Passphrase parameter.
Encryption Key ID
The Key ID of the recipient public key when using the Keypair encryption method. The format can be 8 hex digits for the short key ID, 16 hex digits for the long key ID, or 40 hex digits for the fingerprint. Spaces are allowed, but are not counted in the length. This parameter can be used in place or together with the Encryption Key User ID to select a more specific key.

Encryption Parameters
Encrypt	Whether to encrypt the data in the PGP message.
Symmetric Algorithm	Symmetric algorithm to be used for encryption.
Encryption Method	Determines how the session key is encrypted, use Passphrase for Password-Based Encryption (PBE), use Keypair to encrypt with a public key.
Encryption Passphrase	Case sensitive passphrase when using the Passphrase encryption method. The passphrase will be used to generate a key encryption key to encrypt the session key.
Public Key Ring	Location of the public key ring containing the encryption public key when using the Keypair encryption method.
Encryption Key User ID	User ID of the recipient public key when using the Keypair encryption method. The format can be =name for the exact User ID, user@host to match only the email address, or <user@host> optionally surrounded by ignored comments to match only the value within angle brackets against the email address. For backwards compatibility, this parameter defaults to the value of the Encryption Passphrase parameter.
Encryption Key ID	The Key ID of the recipient public key when using the Keypair encryption method. The format can be 8 hex digits for the short key ID, 16 hex digits for the long key ID, or 40 hex digits for the fingerprint. Spaces are allowed, but are not counted in the length. This parameter can be used in place or together with the Encryption Key User ID to select a more specific key.

The Encrypt parameter determines whether the message is encrypted. When the message is not encrypted, the remaining parameters of this group are ignored.

The Symmetric Algorithm parameter specifies the algorithm to be used for encryption. This implicitly determines the size of the session key. The DES algorithm is not recommended since it is now considered too weak.

The Encryption Method determines how the session key is encrypted. Choose between Passphrase or Keypair.

With the Passphrase method, the Encryption Passphrase is used to generate a key encryption key to encrypt the session key. The Public Key Ring, Encryption Key User ID, and Encyption Key ID are ignored.

With the Keypair method, the recipient public key is used as the key encryption key. The Encryption Key User ID and the Encryption Key ID specify which public key will be retrieved from the Public Key Ring. The User ID is possibly ambiguous but is convenient for humans. The Key ID should be used when the recipient key must be determined more precisely. Both parameters are optional. The recipient key must satisfy both criteria when both parameters are used. When both parameters are absent, the default encryption key is chosen. The selected key must not be revoked and it must support encryption. The Encryption Passphrase and the Encryption Key User ID parameters used to be a single parameter. For backwards compatibility, the Encryption Key ID defaults to the value of the Encryption Passphrase parameter. Except for this, the Encryption Passphrase parameter is ignored with the Keypair method.

Edges

The following table lists and describes the edges that are returned by the PGP Encryption and Signature Service (com.ibi.agents.PGPEncrypt).

Edge Name	Description
success	The message was successfully packaged with PGP.
fail_parse	An iFL or XPath expression could not be evaluated.
fail_security	The message could not be packaged.

Configuring the PGP Decryption and Verification Service

Syntax:

com.ibi.agents.PGPDecryptAgent

Description:

This service decrypts and verifies the signature of a message packaged with Pretty Good Privacy (PGP). When successful, this service returns the original clear text message. PGP is specified in RFC4880. This section assumes you are familiar with PGP.

The service accepts messages constructed in various ways. The first input message might be encrypted and unsigned. The second message might be unencrypted and signed, and so on. The structure of the message determines how it is processed. Special Registers (SREGs) describe the structure that was actually found. It is also possible to insist that input messages must be signed.

Parameters:

The following tables describe the parameters for the PGP Decryption and Verification Service. Each table is followed by a discussion of that parameter group.

Decryption Parameters
Parameter Name
Description
Decryption Key Passphrase
Case sensitive passphrase to decrypt the session key. This parameter is optional, and will be used when the session key has been encrypted with a passphrase.
Secret Key Ring
Location of the secret key ring containing the private keys to decrypt the session keys. This parameter is optional, and will be used when the session key has been encrypted with a public key.
Private Key Passphrase
Case sensitive passphrase to unlock the Decryption Private Key within the Secret Key Ring. This parameter is optional, and will be used when the session key has been encrypted with a public key.

Decryption Parameters
Decryption Key Passphrase	Case sensitive passphrase to decrypt the session key. This parameter is optional, and will be used when the session key has been encrypted with a passphrase.
Secret Key Ring	Location of the secret key ring containing the private keys to decrypt the session keys. This parameter is optional, and will be used when the session key has been encrypted with a public key.
Private Key Passphrase	Case sensitive passphrase to unlock the Decryption Private Key within the Secret Key Ring. This parameter is optional, and will be used when the session key has been encrypted with a public key.

These parameters come into play when the input message is encrypted. The Decryption Key Passphrase is used to decrypt the session key if it was encrypted with a Passphrase. If the session key was encrypted with a public key, then the Secret Key Ring is searched for a private key matching the Key ID indicated in the message. The Private Key Passphrase is needed to unlock the private key. This is because the private key is encrypted within the secret key ring.

Signature Verification Parameters
Parameter Name
Description
Signature Required
If set, incoming messages require a valid signature.
Public Key Ring
Location of the public key ring containing the signature public keys.
Acceptable Hash Algorithms
Space separated list of hash names that can be used in PGP signatures, other hashes will cause a validation failure before being evaluated. The intention is to forbid weak algorithms defined in the PGP specification. The default is SHA1 SHA224 SHA256 SHA384 SHA512. Other hash names include MD5, RIPEMD160, DOUBLE_SHA, MD2, TIGER_192, and HAVAL_5_160.

Signature Verification Parameters
Signature Required	If set, incoming messages require a valid signature.
Public Key Ring	Location of the public key ring containing the signature public keys.
Acceptable Hash Algorithms	Space separated list of hash names that can be used in PGP signatures, other hashes will cause a validation failure before being evaluated. The intention is to forbid weak algorithms defined in the PGP specification. The default is SHA1 SHA224 SHA256 SHA384 SHA512. Other hash names include MD5, RIPEMD160, DOUBLE_SHA, MD2, TIGER_192, and HAVAL_5_160.

When the Signature Required parameter is set and the input message is unsigned, an error is reported and the fail_unsigned edge is followed.

The remaining parameters come into play when the input message is signed. The Public Key Ring is searched for the signer public key matching the Signer Key ID indicated in the message. This public key is used to read the signature in the message.

The Acceptable Hash Algorithms parameter can be used to reject signatures produced with weak hash algorithms. The value of the parameter is a space-separated list of acceptable hash algorithm names. The default is SHA1 SHA224 SHA256 SHA384 SHA512. When the signature in the input message is based on a hash algorithm that does not appear in the list, an error is produced and the fail_security edge is followed. The other possible hash names are: MD5, RIPEMD160, DOUBLE_SHA, MD2, TIGER_192, HAVAL_5_160. Some of these hash names are not necessarily weak, but they are not mentioned in RFC4880 and therefore are not standard in OpenPGP.

Edges

The following table lists and describes the edges that are returned by the PGP Decryption and Verification Service (com.ibi.agents.PGPDecryptAgent).

Edge Name	Description
success	The message was successfully unpackaged with PGP.
fail_parse	An iFL or XPath expression could not be evaluated.
fail_security	The message could not be unpackaged or the signature hash algorithm is not acceptable.
fail_unsigned	The message was successfully unpacked but was unsigned and the Signature Required parameter is on.

Special Registers (SREGs)

The following table describes the Special Registers (SREGs) that are assigned upon successful unpackaging of the PGP message.

Special Register Name	Description
pgp_encrypted	A value of true is returned if the PGP message was encrypted. Otherwise, a value of false is returned.
pgp_signed	A value of true is returned if the PGP message was signed. Otherwise, a value of false is returned.
pgp_signer	The user ID of the first signer of the first signature.
pgp_filename	The file name attribute of the literal data packet.

General Parameters
Parameter Name	Description
Armor	Determines whether the binary message will be armored for transfer in ASCII.
Literal Filename	The file name to appear in the Literal Data Packet. The receiving program may use this name when storing the data to disk. The special value _CONSOLE means the data is unusually sensitive.