KeyMgr Module

Properties   Methods   Events   Config Settings   Errors  

The KeyMgr module is used to create and manage OpenPGP keys.

Syntax

IPWorksEncrypt.Keymgr

Remarks

The KeyMgr class can be used to perform a variety of key-related actions. You can create, delete, import, export, and manage keys. Both individual keys and keyrings can be created and used.

Property List

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

Method List

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

Event List

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

Config Settings

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

Key Property (KeyMgr Module)

The currently selected key.

Syntax

• Swift
• Objective-C

public var key: Key {
  get {...}
  set {...}
}

@property (nonatomic,readonly,assign,getter=keyCurve) NSString* keyCurve;

- (NSString*)keyCurve;

@property (nonatomic,readonly,assign,getter=keyEffectiveDate) NSString* keyEffectiveDate;

- (NSString*)keyEffectiveDate;

@property (nonatomic,readwrite,assign,getter=keyEncoded,setter=setKeyEncoded:) NSString* keyEncoded;

- (NSString*)keyEncoded;
- (void)setKeyEncoded :(NSString*)newKeyEncoded;

@property (nonatomic,readwrite,assign,getter=keyEncodedB,setter=setKeyEncodedB:) NSData* keyEncodedB;

- (NSData*)keyEncodedB;
- (void)setKeyEncodedB :(NSData*)newKeyEncoded;
@property (nonatomic,readonly,assign,getter=keyExpirationDate) NSString* keyExpirationDate;

- (NSString*)keyExpirationDate;

@property (nonatomic,readonly,assign,getter=keyFingerprint) NSString* keyFingerprint;

- (NSString*)keyFingerprint;

@property (nonatomic,readonly,assign,getter=keyId) NSString* keyId;

- (NSString*)keyId;

@property (nonatomic,readonly,assign,getter=keyOtherUserIds) NSString* keyOtherUserIds;

- (NSString*)keyOtherUserIds;

@property (nonatomic,readwrite,assign,getter=keyPassphrase,setter=setKeyPassphrase:) NSString* keyPassphrase;

- (NSString*)keyPassphrase;
- (void)setKeyPassphrase :(NSString*)newKeyPassphrase;

@property (nonatomic,readonly,assign,getter=keyPublicKey) NSString* keyPublicKey;

- (NSString*)keyPublicKey;

@property (nonatomic,readonly,assign,getter=keyPublicKeyAlgorithm) NSString* keyPublicKeyAlgorithm;

- (NSString*)keyPublicKeyAlgorithm;

@property (nonatomic,readonly,assign,getter=keyPublicKeyLength) int keyPublicKeyLength;

- (int)keyPublicKeyLength;

@property (nonatomic,readonly,assign,getter=keyRevoked) BOOL keyRevoked;

- (BOOL)keyRevoked;

@property (nonatomic,readonly,assign,getter=keySecretKey) NSString* keySecretKey;

- (NSString*)keySecretKey;

@property (nonatomic,readonly,assign,getter=keySecretKeyAvailable) BOOL keySecretKeyAvailable;

- (BOOL)keySecretKeyAvailable;

@property (nonatomic,readonly,assign,getter=keyUsage) NSString* keyUsage;

- (NSString*)keyUsage;

@property (nonatomic,readonly,assign,getter=keyUsageFlags) int keyUsageFlags;

- (int)keyUsageFlags;

@property (nonatomic,readwrite,assign,getter=keyUserId,setter=setKeyUserId:) NSString* keyUserId;

- (NSString*)keyUserId;
- (void)setKeyUserId :(NSString*)newKeyUserId;

 

Default Value

""

Remarks

This property holds the currently selected key. It is populated after calling ImportKey or after setting Keyring. This may also be set to directly load an existing key. Both public keys and secret keys are supported.

This property is read-only.

Keyring Property (KeyMgr Module)

The location on disk of the keyring.

Syntax

• Swift
• Objective-C

public var keyring: String {
  get {...}
}

@property (nonatomic,readonly,assign,getter=keyring) NSString* keyring;

- (NSString*)keyring;

Default Value

""

Remarks

To load a keyring use the LoadKeyring method.

This property is read-only.

AddRevoker Method (KeyMgr Module)

Adds a designated revoker to the key.

Syntax

• Swift
• Objective-C

public func addRevoker(userId: String) throws -> Void

- (void)addRevoker:(NSString*)userId;

Remarks

This method adds a designated revoker to the selected Key. The UserId parameter specifies the revoker to add. The revoker's key must be present in the current keyring. Use this with caution: once added, a revoker cannot be removed. The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.

The UserId format is:

FirstName LastName (Comment) <Email>

AddUserId Method (KeyMgr Module)

Adds the specified user Id to the current key.

Syntax

• Swift
• Objective-C

public func addUserId(userId: String) throws -> Void

- (void)addUserId:(NSString*)userId;

Remarks

The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.

The UserId format is:

FirstName LastName (Comment) <Email>

ChangeExpirationDate Method (KeyMgr Module)

Changes the expiration date of the key.

Syntax

• Swift
• Objective-C

public func changeExpirationDate(expirationDate: Int32) throws -> Void

- (void)changeExpirationDate:(int)expirationDate;

Remarks

This method changes the expiration date of the current Key. The ExpirationDate parameter specifies the number of days for which the key is valid starting today. For instance a value of "31" means the key is valid for the next 31 days.

The special value "0" means the key will never expire.

The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.

Note: See KeyValidityTime for information on specifying the expiration date when creating the key with CreateKey.

ChangePassphrase Method (KeyMgr Module)

Changes the passphrase of the current key.

Syntax

• Swift
• Objective-C

public func changePassphrase(passphrase: String) throws -> Void

- (void)changePassphrase:(NSString*)passphrase;

Remarks

The Passphrase parameter specifies the new passphrase.

The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.

Config Method (KeyMgr Module)

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)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.

CreateKey Method (KeyMgr Module)

Creates an OpenPGP key pair.

Syntax

• Swift
• Objective-C

public func createKey(userId: String, passphrase: String) throws -> Void

- (void)createKey:(NSString*)userId :(NSString*)passphrase;

Remarks

This method creates a new OpenPGP key pair. The UserId parameter specifies the user Id of the key.

The UserId format is:

FirstName LastName (Comment) <Email>

Additional configuration settings may be set to further configure the details of the key being created. Please see the following settings for details:

• KeyEncryptionAlgorithm
• KeyUsage
• KeyValidityTime
• PublicKeyLength
• PublicKeyAlgorithm
• PublicKeySignatureHashAlgorithm
• Curve
• SubKeyCurve

CreateSubKey Method (KeyMgr Module)

Creates a new subkey.

Syntax

• Swift
• Objective-C

public func createSubKey() throws -> Void

- (void)createSubKey;

Remarks

This method creates a new subkey. Before calling this method the KeyId property must be set to a valid private key.

The following settings may optionally be set to define specific values for the created subkey:

• KeyValidityTime
• PublicKeyLength
• SubKeyAlgorithm
• SubKeyCurve
• SubKeyUsage

DeleteKey Method (KeyMgr Module)

Deletes the specified key.

Syntax

• Swift
• Objective-C

public func deleteKey(userId: String) throws -> Void

- (void)deleteKey:(NSString*)userId;

Remarks

This method deletes the key specified by UserId from the current keyring. Below is a table of the type of Ids that may be specified to identify the key:

ExportPublicKey Method (KeyMgr Module)

Exports the public key of the current key.

Syntax

• Swift
• Objective-C

public func exportPublicKey(fileName: String, useAsciiArmor: Bool) throws -> Void

- (void)exportPublicKey:(NSString*)fileName :(BOOL)useAsciiArmor;

Remarks

This method exports the public key of the currently selected Key. The FileName parameter specifies the file on disk to which the public key will be written. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.

Note: When UseAsciiArmor is set to True the VersionHeader setting may also be set to specify your own header value.

ExportSecretKey Method (KeyMgr Module)

Exports the private key of the current key.

Syntax

• Swift
• Objective-C

public func exportSecretKey(fileName: String, useAsciiArmor: Bool) throws -> Void

- (void)exportSecretKey:(NSString*)fileName :(BOOL)useAsciiArmor;

Remarks

This method exports the private key of the currently selected Key. The FileName parameter specifies the file on disk that the private key will be written to. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.

ImportKey Method (KeyMgr Module)

Imports the key specified by UserId to the current keyring.

Syntax

• Swift
• Objective-C

public func importKey(fileName: String, userId: String) throws -> Void

- (void)importKey:(NSString*)fileName :(NSString*)userId;

Remarks

This method imports the key specified by UserId from the key file specified by FileName into the current Keyring. The imported key will be automatically selected and available in the Key property.

If the FileName specifies a key file which contains multiple keys only the key belonging to UserId will be imported.

If UserId is set to "*" or "" (empty string) all keys in the key file will be imported. The ImportAllKeys setting controls the behavior of the class in this case.

Note: If you simply wish to select a key in the current ring set KeyUserId instead.

ImportKeyB Method (KeyMgr Module)

Imports the key specified by UserId to the current keyring.

Syntax

• Swift
• Objective-C

public func importKeyB(data: Data, userId: String) throws -> Void

- (void)importKeyB:(NSData*)data :(NSString*)userId;

Remarks

This method imports the key specified by UserId from the key data specified by Data into the current Keyring. The imported key will be automatically selected and available in the Key property.

If the Data specifies key data that contains multiple keys only the key belonging to UserId will be imported.

If UserId is set to "*" or "" (empty string) all keys in the key data will be imported. The ImportAllKeys setting controls the behavior of the class in this case.

Note: If you simply wish to select a key in the current ring set KeyUserId instead.

ListKeys Method (KeyMgr Module)

Lists keys in the specified Keyring .

Syntax

• Swift
• Objective-C

public func listKeys() throws -> String

- (NSString*)listKeys;

Remarks

This method lists the keys (public/private key pairs) in the specified keyring. The results are provided through the KeyList event.

KeyList data will also be returned from this method, however it is recommended to use the KeyList event if possible.

ListSignatures Method (KeyMgr Module)

Lists all signatures of the current key.

Syntax

• Swift
• Objective-C

public func listSignatures() throws -> String

- (NSString*)listSignatures;

Remarks

This method lists all the signatures of the currently selected key. The SignatureList event will fire for each signature.

SignatureList data will also be returned from this method. However, it is recommended to use the SignatureList event if possible.

ListSubkeys Method (KeyMgr Module)

Lists the subkeys of the currently selected key.

Syntax

• Swift
• Objective-C

public func listSubkeys() throws -> String

- (NSString*)listSubkeys;

Remarks

This method lists all subkeys of current key. The SubkeyList event will be fired for each subkey.

SubkeyList data will also be returned from this method, however it is recommended to use the SubkeyList event if possible.

LoadKeyring Method (KeyMgr Module)

Loads the keyring from disk.

Syntax

• Swift
• Objective-C

public func loadKeyring(keyringPath: String) throws -> Void

- (void)loadKeyring:(NSString*)keyringPath;

Remarks

This method loads the keyring from disk. If the keyring is stored in a directory, set KeyringPath to the directory. The directory must contain the files "secring.gpg" and "pubring.gpg". A keyring may also be stored in a single file. If the keyring is a file KeyringPath should be set to the path of the file.

When this method is called the class will read the keyring and populate the Key property with the first key found in the keyring. Set KeyUserId to select a different key in the current keyring.

LoadKeyringB Method (KeyMgr Module)

Loads the keyring from SecretKeyringData and PublicKeyringData .

Syntax

• Swift
• Objective-C

public func loadKeyringB(secretKeyringData: Data, publicKeyringData: Data) throws -> Void

- (void)loadKeyringB:(NSData*)secretKeyringData :(NSData*)publicKeyringData;

Remarks

This method loads the keyring from SecretKeyringData and PublicKeyringData.

When this method is called the class will read the keyring and populate the Key property with the first key found in the keyring. Set KeyUserId to select a different key in the current keyring.

Reset Method (KeyMgr Module)

Resets the component properties.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

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

RevokeKey Method (KeyMgr Module)

Revokes the specified key.

Syntax

• Swift
• Objective-C

public func revokeKey(keyId: String) throws -> String

- (NSString*)revokeKey:(NSString*)keyId;

Remarks

This method revokes the key specified by KeyId and returns the revocation certificate.

When creating a revocation certificate there are two supported formats. The first format includes only the revocation signature. This format is returned by this method. The second format includes both the public key and the revocation signature. This format can be obtained by calling ExportPublicKey after calling this method. Both formats are common, and both formats are acceptable when calling ImportKey.

Before calling this method a key must be selected and available in the Key* properties.

The KeyId may be the Id of the main key or a subkey.

SaveKeyring Method (KeyMgr Module)

Saves the current Keyring to disk.

Syntax

• Swift
• Objective-C

public func saveKeyring(keyringPath: String) throws -> Void

- (void)saveKeyring:(NSString*)keyringPath;

Remarks

This method saves the current keyring to disk. There are two output options. The keyring may either be saved to a single key file or may be saved to a directory.

To save the keyring to a directory set KeyringPath to the path. The directory must already exist. The class will create a "pubring.gpg" and "secring.gpg" file in the specified directory. If the files already exist they will be overwritten.

To save the keyring to a key file set KeyringPath to a path and file name. If the file already exists it will be overwritten.

SignUserId Method (KeyMgr Module)

Signs the specified user Id of the current key.

Syntax

• Swift
• Objective-C

public func signUserId(userId: String, issuerUserId: String) throws -> Void

- (void)signUserId:(NSString*)userId :(NSString*)issuerUserId;

Remarks

This method signs the UserId with the IssuerUserId.

To sign all user Ids in the current key set the UserId parameter to "*".

The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.

VerifyPassphrase Method (KeyMgr Module)

Verifies the passphrase of specified key.

Syntax

• Swift
• Objective-C

public func verifyPassphrase(passphrase: String) throws -> Bool

- (BOOL)verifyPassphrase:(NSString*)passphrase;

Remarks

This method verifies the passphrase of the key specified by UserId.

If the password is correct, this method returns True; otherwise, this method returns False.

Error Event (KeyMgr Module)

Fired when information is available about errors during data delivery.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)description;

Remarks

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

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.

KeyList Event (KeyMgr Module)

Fires for each key in the keyring when ListKeys is called.

Syntax

• Swift
• Objective-C

func onKeyList(userId: String, keyId: String, fingerprint: String, hasSecretKey: Bool, publicKeyAlgorithm: String, publicKeyLength: Int32, curve: String)

- (void)onKeyList:(NSString*)userId :(NSString*)keyId :(NSString*)fingerprint :(BOOL)hasSecretKey :(NSString*)publicKeyAlgorithm :(int)publicKeyLength :(NSString*)curve;

Remarks

This event fires once for each key in the Keyring when ListKeys is called.

UserId holds the current user Id of the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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

BF52A0AB

Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

HasSecretKey returns True if the key contains a secret key.

PublicKeyAlgorithm is the public key algorithm. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA

PublicKeyLength is the length of the public key. Common values are 512, 1024, and 2048. If the PublicKeyAlgorithm is ECDSA or EdDSA the length of the public key is determined by the Curve. Possible lengths are:

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA or EdDSA. Possible values are:

KeyPassphrase Event (KeyMgr Module)

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

Syntax

• Swift
• Objective-C

func onKeyPassphrase(userId: String, keyId: String, passphrase: inout String)

- (void)onKeyPassphrase:(NSString*)userId :(NSString*)keyId :(NSString**)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 KeyPassphrase property 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

SignatureList Event (KeyMgr Module)

Fires for each signature of the current key when ListSignatures is called.

Syntax

• Swift
• Objective-C

func onSignatureList(userId: String, issuerKeyId: String, issuerUserId: String, publicKeyAlgorithm: String, curve: String, hashAlgorithm: String, effectiveDate: String, signatureClass: Int32, validityStatus: Int32)

- (void)onSignatureList:(NSString*)userId :(NSString*)issuerKeyId :(NSString*)issuerUserId :(NSString*)publicKeyAlgorithm :(NSString*)curve :(NSString*)hashAlgorithm :(NSString*)effectiveDate :(int)signatureClass :(int)validityStatus;

Remarks

This event fires once for each signature of the current key when ListSignatures is called.

UserId holds the current user Id of the key.

The UserId format is:

FirstName LastName (Comment) <Email>

IssuerKeyId is the hex-encoded, 4- or-8-byte Id of the issuer's key. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance: BF52A0AB

IssuerUserId is the user Id of the issuer. If this is empty the issuer's key could not be found in the current keyring.

PublicKeyAlgorithm is the public key algorithm. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA or EdDSA. Possible values are:

HashAlgorithm is the hash algorithm used by the signature. Possible values are:

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

EffectiveDate is the date when this signature became valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00 .

SignatureClass is the type of signature. Possible values are:

ValidityStatus specifies the current validity status of the signature. Possible values are:

Status Event (KeyMgr Module)

Shows the progress of the operation.

Syntax

• Swift
• Objective-C

func onStatus(message: String)

- (void)onStatus:(NSString*)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.

SubkeyList Event (KeyMgr Module)

Fires once for each subkey listed when ListSubkeys is called.

Syntax

• Swift
• Objective-C

func onSubkeyList(keyId: String, fingerprint: String, publicKeyAlgorithm: String, publicKeyLength: Int32, curve: String, usageFlags: Int32, usage: String, effectiveDate: String, expirationDate: String, revoked: Bool)

- (void)onSubkeyList:(NSString*)keyId :(NSString*)fingerprint :(NSString*)publicKeyAlgorithm :(int)publicKeyLength :(NSString*)curve :(int)usageFlags :(NSString*)usage :(NSString*)effectiveDate :(NSString*)expirationDate :(BOOL)revoked;

Remarks

This event fires once for each subkey when ListSubkeys is called.

KeyId 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

Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

PublicKeyAlgorithm is the public key algorithm. Possible values are:

• RSA
• Elgamal
• ECDH (Only used with ECDSA and EdDSA keys)

PublicKeyLength is the length of the public key. Common values are 512, 1024, and 2048.

Curve is the curve used by the key when PublicKeyAlgorithm is ECDH. Possible values are:

Usage is the textual description of UsageFlags.

The value will be of one or more of the following strings, separated by commas:

• Certifying Other Certificates
• Signing Emails and Files
• Encrypting Emails and Files
• Split Key
• Authenticate Against Servers
• Group Key

UsageFlags is an integer flag that shows the intended use for the key. The value is a combination of the following flags:

EffectiveDate is the date when this key became valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00.

ExpirationDate is the date the key expires. After this date the key will no longer be valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00. If the ExpirationDate is not populated this indicates that the key never expires.

Revoked Indicates whether the subkey is revoked or not.

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 init(keyPath: )

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

public init(keyData: )

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

public init(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 init(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 (KeyMgr Module)

KeyMgr Config Settings

Base Config Settings

Trappable Errors (KeyMgr Module)

OpenPGP Errors