IPWorks Encrypt 2020 Android Edition

Questions / Feedback?

Openpgp Configuration

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

OpenPGP Configuration Settings

AllowEmptyInput:   Whether to allow empty files for input.

This setting controls whether the component allows empty input when processing. When True, the component will process 0 byte files specified by InputFile, or 0 byte messages specified by InputMessage. The default value is False.

AllowOldPacketType:   Whether to allow the older encrypted packet type.

By default the component will only encrypt data using the newer and more secure integrity protected data packet type. Old implementations such as PGP 6.5.8 may require the older less secure data packet type.

When set to True the component will read the features from the recipient key to determine if the older packet type is required. If the key does require the old packet type, then the older packet type will be used. If the key does not require the old packet type, then the new integrity protected packet type will still be used.

By default this value is False. This means under no conditions is the older less secure packet type used. The newer integrity protected packet type is always used.

Only enable this setting if you have a requirement to do so.

CloseInputStreamAfterProcessing:   Determines whether or not the input stream is closed after processing.

Determines whether or not the input stream set by SetInputStream is closed after processing is complete. The default value is True.

CloseOutputStreamAfterProcessing:   Determines whether or not the output stream is closed after processing.

Determines whether or not the output stream set by SetOutputStream is closed after processing is complete. The default value is True.

CompressionLevel:   The level of compression used.

This setting specifies the level of compression used: possible values depend on the value of CompressionMethod and are detailed below.

zlib 1-6
zip 1-6
bzip21-9

Higher values will cause the component to compress better; lower values will cause the component to compress faster. The default value for all methods is 4.

DeleteOutputFileOnError:   Whether to delete the output file on an error.

Set this to true to automatically delete any partially written OutputFile if an error occurs. The default is false

DetachedSignatureData:   The detached signature.

This setting is used to specify the detached signature before calling VerifySignature. The message data should be specified normally and this setting should be set to the detached signature data. Both hex-string and OpenPGP ASCII-armored message formats are allowed. Hex-encoded data should be provided as a string like so:

89011C04000102000605025100459B000A0910E2...
EnsureValidDSASignatureHashAlgorithm:   Whether or not to select a suitable signature hash algorithm automatically.

This setting specifies whether the component ensures a valid hash algorithm is selected for use with the loaded DSA or ECDSA key. The default value is True.

DSA Notes

DSA requires that the hash be 160 bits or larger, which means MD5 is not a suitable algorithm. When DSA Signature Hash Algorithm selection is enabled (default) the component will use the preferred algorithm from the key if it meets the requirements for DSA. If the preferred algorithm is MD5 and does not meed the requirements for DSA the component will automatically use a suitable algorithm based on the Q element of the DSA key (may be SHA1, SHA224, or SHA256).

ECDSA Notes

The ECDSA Signature Hash Algorithm requirements are directly related to the Curve used by the key. When this setting is enabled (default) the component will use the preferred algorithm from the key if it meets the requirements for ECDSA. If the preferred algorithm does not meet the requirements the component will automatically select a valid hash algorithm based on the curve as follows:

CurveHash Algorithm
secp256r1 SHA256
secp384r1 SHA384
secp521r1 SHA512
secp256k1 SHA256

FileName:   The original name of the encrypted file.

When encrypting, this configuration setting can be used to specify the original name of the encrypted data. When specifying an InputFile to encrypt from, this is included automatically in the encrypted packet. After decrypting, this will contain the file name of the original encrypted file.

ForceV3Signature:   Whether to use v3 signatures.

This setting is used to force v3 signatures for compatibility with older PGP implementations (versions 5 through 7).

The default value is False.

KeyIdLength:   The length of the KeyId available.

This controls the length of KeyId available when RecipientInfo fires. Possible values are 4 (default) or 8.

KeySelectionMethod:   The method used to select a key for encryption or signing.

When more than one key is present this component can be configured to automatically select a key based on certain criteria (described below) or allow for manual selection.

0 Automatic selection, first suitable subkey. Expired keys accepted.
1 Automatic selection, first suitable subkey. Expired keys not accepted.
2 Automatic selection, newest suitable subkey. Expired keys not accepted (Default).
99 Manual Selection.

A key's suitability is determined by its usage flags.

Manual Selection

To manually select a key for any operation pass the key's Id in the constructor.

  Openpgp pgp = new Openpgp();
  pgp.Config("KeySelectionMethod=99");
  pgp.RecipientKeys.Add(new Key(@"C:\path\to\key.asc", "7CA1376C39768977")); // Key with Id 7CA1376C39768977 will be used for encryption.

LogLevel:   Specifies the level of detail that is logged.

This setting controls the level of detail that is logged through the Status event. Possible values are:

0 (None)No events are logged.
1 (Info - default)Informational events are logged.
2 (Verbose)Detailed data is logged.
3 (Debug)Debug data is logged.

PGPZipDir:   The directory used when creating or extracting a PGP zip file.

A PGP zip file is a Tar archive that is encrypted. It is commonly used by utilities to protect multiple files in one OpenPGP message. The component supports creating and extracting these types of files.

  • To create a PGP zip file set this value to a location on disk including a filemask and call Encrypt. For instance:
    OpenPGP1.Config("PGPZipDir=C:\MyFiles\*.txt");
    OpenPGP1.OutputFile = "C:\PGPZip.pgp";
    OpenPGP1.Encrypt();
    The created file returned in the OutputFile property is the PGP zip. If InputFile is specified it is used to temporarily hold the Tar archive while creating the PGP zip file. The temporary file is not automatically deleted. If InputFile is not specified the Tar archive is held in memory while creating the PGP zip file.
  • To extract a PGP zip file set this value to a location on disk and call Decrypt. For instance:
    OpenPGP1.Config("PGPZipDir=C:\MyFiles");
    OpenPGP1.InputFile = "C:\PGPZip.pgp";
    OpenPGP1.Decrypt();
    The extracted files will be present in the specified directory. If OutputFile is specified it is used to temporarily hold the Tar archive. The temporary file is not automatically deleted. If OutputFile is not specified the Tar archive is held in memory while extracting the PGP zip file. Note that if the OpenPGP message supplied is not a PGP zip file the decryption will occur as normal without error.

ProgressEventThreshold:   The amount of data in bytes to process before firing the progress event.

When encrypting or decrypting, the Progress event is fired as data is processed by the component. When this setting is specified, the event will only fire after processing at least the specified number of bytes. The default value is 0.

PublicKeyringFile:   The file name of the public keyring file.

This specifies the name of the public keyring file. The default value is "pubring.gpg". This may be set to a file name only, or a full path including the file name.

ReadFromProgressEvent:   Whether to read input data from inside the progress event.

When set to True this setting allows input data to be specified from within the Progress event. The component will repeatedly fire the Progress event to ask for data. Inside the event set InputMessage when the Operation parameter of the event is 1 (Read). When all data has been provided set the IsEOF parameter of the event to True. This allows input data to be chunked and provided piece by piece. The default value is False.

RecursiveDecryptMode:   Whether the encrypted data should be decrypted recursively.

In some instances data will be encrypted multiple times. This configuration option determines how the component will handle this situation. Options are:

0Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default)
1Always attempt recursive decryption.
2Never attempt recursive decryption.

RequireEncryption:   Whether to throw an error when decrypting and encryption is not detected.

By default, the component's decryption methods will succeed if the message is not encrypted. To cause an error to be thrown in this case, set this option to true.

The default value is false.

RequireIntegrityProtectedPacket:   Whether an MDC packet is required for decryption.

When set to true, the component will throw an exception if the message being decrypted does not contain a Message Detection Code (MDC) packet. The default value is false.

RequireSignature:   Whether to throw an error when verifying a signature and no signature is found.

By default, the component's signature verification methods will succeed if the message is not signed. To cause an error to be thrown in this case, set this option to true.

The default value is false.

RequireValidSignature:   Specifies if an invalid signature is considered an error condition.

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

SecretKeyringFile:   The file name of the secret keyring file.

This specifies the name of the secret keyring file. The default value is "secring.gpg". This may be set to a file name only, or a full path including the file name.

SplitHeaders:   Controls whether ASCII Armor headers are split or not.

By default, when headers are specified via MessageHeaders, the component will split headers over a certain length onto multiple lines. This is done to avoid potential errors during transport of the message. If false, the headers will be on one line regardless of length. The default value is True.

SymmetricPassphrase:   The password used for symmetric encryption or decryption.

This setting specifies the passphrase when using symmetric encryption. If a value is provided, symmetric encryption/decryption will be attempted. In this case no keys are used for either encryption or decryption. Only Encrypt and Decrypt are valid operations when a value is set. Sign, SignAndEncrypt, VerifySignature, and DecryptAndVerifySignature are not valid operations when using this option.

UseFipsCompliantAlgorithms:   Restricts the usage to FIPS compliant algorithms only.

When enabled the component will only support FIPS compliant algorithms. If a non-FIPS compliant algorithm is used an exception is thrown. The following algorithms are supported when this setting is True:

  • 3DES
  • AES128
  • AES192
  • AES256
  • RSA
  • DSA
  • SHA1
  • SHA256
  • SHA384
  • SHA512
  • SHA224
The default value is False.
VersionHeader:   The Version header value in the ASCII armored OpenPGP message.

This setting specifies the Version header value included in the ASCII armored OpenPGP message. This may be set before calling Encrypt, Sign, or SignAndEncrypt. The default value is "IPWorks! OpenPGP 2016".

This setting will be populated after calling Decrypt, VerifySignature, or DecryptAndVerifySignature.

WriteToProgressEvent:   Whether to write output data so it is accessible from inside the progress event.

When set to True this setting allows output data to be obtained from within the Progress event. The component will repeatedly fire the Progress event to provide output data. Inside the event check OutputMessage when the Operation parameter of the event is 2 (Write). The IsEOF parameter should be checked inside the event to determine when all output data has been provided. This allows output data to be chunked and obtained piece by piece. The default value is False.

Base Configuration Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the component whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g. RuntimeLicense, License File).
  • License Type: The type of license installed (e.g. Royalty Free, Single Server).
UseDaemonThreads:   Whether threads created by the component are daemon threads.

If set to True (default), when the component creates a thread the thread's Daemon property will be explicitly set to True. When set to False the component will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

By default the component will use the system security libraries to perform cryptographic functions. Setting this to True tells the component to use the internal implementation instead of using the system's security API.

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Encrypt 2020 Android Edition - Version 20.0 [Build 8155]