IPWorks OpenPGP 2020 macOS Edition

Questions / Feedback?

KeyMgr Configuration

The class 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 class, access to these internal properties is provided through the Config method.

KeyMgr Configuration Settings

AllowEmptyPassword:   Whether a key can be created without a password.

This controls whether a password will be used to encrypt a key. When true, CreateKey will accept an empty string as the password, leaving the key unencrypted. The default is false.

ContinueOnInvalidKey:   Whether to continue loading the keyring when an invalid key is found.

This setting determines whether the class will continue loading keys when an invalid key is found. This is applicable when calling LoadKeyring. If set to False (default) the class . If set to True the class will fire the Error event with information about the key which failed to load, and then continue loading additional keys.

CreateRSASubkeyforEncrypt:   Whether to create a subkey when creating an RSA key.

This setting determines whether the class will additionally create a subkey marked for encryption when calling CreateKey when PublicKeyAlgorithm is set to "RSA". The default is true.

CurrentKeyPrimaryKeyUsageFlags:   The usage flags of the currently selected primary key.

When queried, this will return the usage flags of the currently selected primary key, returned in decimal representation. Individual flags may be checked against the list at UsageFlags.

Curve:   The elliptic curve used when calling CreateKey.

This setting specifies the curve to use when creating ECDSA or EdDSA keys. This setting is only applicable when PublicKeyAlgorithm is set to ECDSA or EdDSA. Possible values are:

ValuePublicKeyAlgorithmDescription
secp256r1 ECDSA NIST curve P-256
secp384r1 ECDSA NIST curve P-384
secp521r1 ECDSA NIST curve P-521
Ed25519 EdDSA Ed25519
secp256k1 EdDSA Secp256k1

The default value is secp256r1 for ECDSA keys and Ed25519 for EdDSA keys.

DSAPublicSubKeyLength:   Specifies the public subkey length when creating a DSA key.

This setting is only applicable when creating DSA keys with CreateKey. This specifies the length of the public ElGamal subkey. The value is 0 means this setting is not used and the subkey will have the length defined in PublicKeyLength. The default value is 0.

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

This setting specifies whether the class 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 class 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 class 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 class 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 class will automatically select a valid hash algorithm based on the curve as follows:

CurveHash Algorithm
secp256r1 SHA256
secp384r1 SHA384
secp521r1 SHA512
secp256k1 SHA256

ImportAllKeys:   Whether or not to import all keys found in a key file.

When calling ImportKey with a UserId parameter of "*" or "", the class will import all keys found in the file if this property is set to True (default). If this is set to False when the UserId parameter of ImportKey is set to "*" or "", only the first key found in the file will be imported. The default value is True.

KeyEncryptionAlgorithm:   The encryption algorithm used when creating a key.

Specifies the encryption algorithm to use when calling CreateKey. The default value is "CAST5". Possible values are "CAST5", "3DES", "AES256", "AES192", "AES128", "IDEA", and "BLOWFISH".

KeyIdLength:   Specifies the length of the key's Id.

When querying the Id property the value will be returned with the length (in octets) specified. The default value is 4. The only other acceptable value is 8.

KeyUsage:   Flags that show intended use for the key being created.

When calling CreateKey this setting defines the flags that show the intended use for the key. The default value is (0x0F). The value of KeyUsage is a combination of the following flags:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The private component of this key may be in the possession of more than one person.

KeyValidityTime:   The validity period for the key being created.

When CreateKey creates a new key, the key is valid the moment it is created. KeyValidityTime determines the number of days until expiration. The default value is 365 days. The special value 0 means the key will never expire.

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.

PublicKeyAlgorithm:   The public key algorithm for the key being created.

Specifies the public key algorithm to use when creating the key via CreateKey. The default value is "RSA". Possible values are:

  • RSA
  • DSA
  • ECDSA
  • EdDSA
  • RSA-Legacy

The "RSA-Legacy" algorithm should not be used under normal circumstances. It should only be used to create PGP 2.6.2 compatible keys, when required. This type of key will not have subkeys.

Note: When creating a DSA key only PublicKeyLength values of 512 and 1024 are supported. Additionally the PublicKeySignatureHashAlgorithm value "MD5" is not supported with DSA keys.

ECDSA and EdDSA Notes

When creating an ECDSA or EdDSA key the PublicKeyLength value is automatically determined based on the Curve. The Curve and SubKeyCurve settings is also applicable.

If Curve and SubKeyCurve are not specified the following defaults will be used:

PublicKeyAlgorithmDefault Curve
ECDSAsecp256r1
EdDSAEd2519

PublicKeyLength:   Specifies the public key length when creating a key.

Specifies the length of the public key when calling CreateKey. The default value is 1024. Common values are 512, 1024, and 2048.

When PublicKeyAlgorithm is set to ECDSA or EdDSA this setting is not applicable and the public key length is automatically determined based on the Curve selected. The public key length values are as follows:

CurvePublic Key Length (bits)
secp256r1256
secp384r1384
secp521r1521
Ed25519 256
secp256k1256

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.

PublicKeySignatureHashAlgorithm:   The public key signature hash algorithm used when creating a key.

This setting specifies the public key signature algorithm to be used when calling CreateKey. The default value is "SHA256". Possible values are:

  • SHA1
  • MD5
  • SHA256 (default)
  • SHA384
  • SHA512
  • SHA224
RawKeyData:   Returns detailed key and keyring data for debugging purposes.

This setting will return detailed debugging information about the current key and keyring.

RevocationCode:   The reason why the key was revoked.

This setting specifies why the key was revoked. It is only applicable if Revoked is True. This may be set before calling RevokeKey and may be inspected after importing and selecting a revoked key. Possible values are:

0No reason specified
1Key is superseded
2Key material has been compromised
3Key is retired and no longer used
4User Id information is no longer valid
100-110Private Use

The default value is 0.

RevocationReason:   Text describing why the key was revoked.

This setting specifies text description of why the key was revoked. It is only applicable if Revoked is True. This may be set before calling RevokeKey and may be queried after importing and selecting a revoked key. The default value is an empty string.

Revoker:   The revoker's key Id.

This setting returns the key Id of the designated revoker associated with this key. This will only be present if a separate revoker was added to the key (for instance by calling AddRevoker). If more than one revoker was added this setting will return a comma-separated list of key Ids.

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.

SubKeyAlgorithm:   The subkey algorithm for the subkey being created.

Specifies the public key algorithm to use when creating the key via CreateKey. The default value is "RSA". Possible values are:

Key AlgorithmSupported Operations
RSA Sign and Encrypt
DSA Sign
Elgamal Encrypt
ECDSA Sign
EdDSA Sign
ECDH Encrypt

SubKeyCurve:   The elliptic curve of the sub key.

When calling CreateKey and PublicKeyAlgorithm is set to ECDSA or EdDSA this setting may optionally be specified to set a curve for the subkey which differs from the key curve specified by Curve. Possible values are:

ValueDescription
secp256r1 NIST curve P-256
secp384r1 NIST curve P-384
secp521r1 NIST curve P-521
Curve25519 Curve25519
Ed25519 Ed25519

The default value for ECDSA keys is the same value as specified in Curve. The default value for EdDSA keys is Curve25519.

Note: It is valid to specify the subkey curve of Curve25519 when Curve is set to secp256r1, secp384r1, or secp521r1. It is also valid to set a subkey curve of secp256r1, secp384r1, or secp521r1 when Curve is set to Ed25519.

SubKeyUsage:   Flags that show intended use for the subkey being created.

When calling CreateSubKey this setting defines the flags that show the intended use for the key. The default value is (0x0C). The value of SubKeyUsage is a combination of the following flags:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The private component of this key may be in the possession of more than one person.

UseFipsCompliantAlgorithms:   Restricts the usage to FIPS compliant algorithms only.

When enabled the class 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 ASCII armored public keys.

This setting specifies the Version header value included in newly created public keys. This includes keys that are exported via ExportPublicKey where the UseAsciiArmor parameter is true. The default value is "IPWorks! OpenPGP v9.0".

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.

CodePage:   The system code page used for Unicode to Multibyte translations.

The default code page is the Active Code Page (0).

The following is a list of valid code page identifiers:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multlingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangeul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8

The following is a list of valid code page identifiers for Mac OS only:

IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class 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).
UseInternalSecurityAPI:   Tells the class whether or not to use the system security libraries or an internal implementation.

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

Copyright (c) 2021 /n software inc. - All rights reserved.
IPWorks OpenPGP 2020 macOS Edition - Version 20.0 [Build 7941]