# GPGContext

> Inherits From:
>   GPGObject : NSObject

> Declared In:
>   GPGME/GPGContext.h

## Class Description

All cryptographic operations in GPGME are performed within a context, which contains the internal state of the operation as well as configuration parameters. By using several contexts you can run several cryptographic operations in parallel, with different configuration.

UserID search patterns (for OpenPGP protocol):

For search pattern, you can give:

- a key ID, in short or long form, prefixed or not by `0x`

- a key fingerprint

- using "=aString", where aString must be an exact match like "=Heinrich Heine <heinrichh@uni-duesseldorf.de>"

- using the email address part, matching exactly: "<heinrichh@uni-duesseldorf.de>"

- using a format like this: "+Heinrich Heine duesseldorf". All words must match exactly (not case sensitive) but can appear in any order in the user ID. Words are any sequences of letters, digits, the underscore and all characters with bit 7 set.

- or a substring matching format like that: "Heine" or "*Heine". By case insensitive substring matching. This is the default mode but applications may want to explicitely indicate this by putting the asterisk in front.

## Defined Types

> #### Synopsis:

> `typedef enum {
> GPGSignatureModeNormal = 0,
> GPGSignatureModeDetach = 1,
> GPGSignatureModeClear = 2
> } GPGSignatureMode;`

> #### Description:

> The GPGSignatureMode type is used to specify the desired type of a signature. The following modes are available:

> GPGSignatureModeNormal | A normal signature is made, the output includes the plaintext and the signature.
> GPGSignatureModeDetach | A detached signature is made.
> GPGSignatureModeClear | A clear text signature is made. The ASCII armor and text mode settings of the context are ignored.

> #### Synopsis:

> `typedef unsigned int GPGKeyListMode;`

> #### Description:

> The key listing mode is a combination of one or multiple of the following bit values:

> GPGKeyListModeLocal | Specifies that the local key-ring should be searched for keys in the key listing operation. This is the default.
> GPGKeyListModeExtern | Specifies that an external source should be searched for keys in the key listing operation. The type of external source is dependant on the crypto engine used. For example, it can be a remote key server or LDAP certificate server.
> GPGKeyListModeSignatures | Specifies that signatures on keys shall be retrieved too. This is a time-consuming operation, and that mode should not be used when retrieving all keys, but only a key per key basis, like when using -refreshKey:.
> GPGKeyListModeValidate | Specifies that the backend should do key or certificate validation and not just get the validity information from an internal cache. This might be an expensive operation and is in general not useful. Currently only implemented for the S/MIME backend and ignored for other backends.

> #### Synopsis:

> `typedef enum {
> GPGAllExceptRootCertificatesInclusion = -2,
> GPGAllCertificatesInclusion = -1,
> GPGNoCertificatesInclusion = -0,
> GPGOnlySenderCertificateInclusion = 1
> }GPGCertificatesInclusion;`

> #### Description:

> Certificates inclusion (S/MIME only):

> GPGAllExceptRootCertificatesInclusion | Include all certificates except the root certificate.
> GPGAllCertificatesInclusion | Include all certificates.
> GPGNoCertificatesInclusion | Include no certificates.
> GPGOnlySenderCertificateInclusion | Include the sender's certificate only.
> n | Include the first n certificates of the certificates path, starting from the sender's certificate. The number n must be positive.

> #### Synopsis:

> `typedef unsigned int GPGImportStatus;`

> #### Description:

> The 'status' value of a key import is a combination of the following bit values:

> GPGImportNewKeyMask | Key is new in the key-ring
> GPGImportNewUserIDMask | Some new userIDs has been imported, or updated
> GPGImportSignatureMask | Some new key signatures have been imported, or updated
> GPGImportSubkeyMask | Some new subkeys have been imported, or updated
> GPGImportSecretKeyMask | Key is a secret key, and is new in the secret key-ring

## Symbolic Constants

> #### Synopsis:

> `GPGCONTEXT_H`

> #### Synopsis:

> `GPGKeyListModeLocal 1`
> `GPGKeyListModeExtern 2`
> `GPGKeyListModeSignatures 4`
> `GPGKeyListModeValidate 256`

> #### Synopsis:

> `GPGImportNewKeyMask 1`
> `GPGImportNewUserIDMask 2`
> `GPGImportSignatureMask 4`
> `GPGImportSubkeyMask 8`
> `GPGImportSecretKeyMask 16`

## Global Variables

> #### Synopsis:

> `NSString * const GPGKeyringChangedNotification;`
> `NSString * const GPGContextKey;`
> `NSString * const GPGChangesKey;`

> #### Description:

> Posted after a modification to a key-ring has been done. For example, after an import or delete operation.

> Object is (currently) nil.

> UserInfo:

> GPGContextKey | The GPGContext instance in which the operation was executed.
> GPGChangesKey | An NSDictionary whose keys are GPGKey instances (secret and public keys) and whose values are NSDictionary instances containing key-value pair @"status" with a GPGImportStatus (as NSNumber), and possibly @"error" with a GPGError (as NSNumber).

> #### Synopsis:

> `NSString * const GPGProgressNotification;`

> #### Description:

> Posted when progress information about a cryptographic operation is available, for example during key generation.

> For details on the progress events, see the entry for the PROGRESS status in the file doc/DETAILS of the GnuPG distribution.

> Currently it is used only during key generation.

> Notification is always posted in the main thread.

> UserInfo:

> @"description" | String...
> @"type" | String containing the letter printed during key generation.
> @"current" | Amount done, as NSNumber.
> @"total" | Amount to be done, as NSNumber. 0 means that the total amount is not known.

> current/total = 100/100 may be used to detect the end of operation.

> #### Synopsis:

> `NSString * const GPGAsynchronousOperationDidTerminateNotification;`
> `NSString * const GPGNextKeyNotification;`
> `NSString * const GPGNextKeyKey;`
> `NSString * const GPGNextTrustItemNotification;`
> `NSString * const GPGNextTrustItemKey;`

> #### Description:

> Posted when an asynchronous operation on a context has been terminated, for example during extended key search, or key upload. Object is the context whose operation has just terminated, successfully or not.

> Notification is always posted in the main thread.

> UserInfo:

> GPGErrorKey | A NSNumber containing a GPGError value

## Instance Variables

> `id _passphraseDelegate;`
> `int _operationMask;`
> `NSMutableDictionary *_operationData;`
> `id _userInfo;`
> `NSMutableSet *_signerKeys;`

> _passphraseDelegate | Passphrase delegate, not retained.
> _operationMask | No description.
> _operationData | No description.
> _userInfo | Object set by user; not used by GPGContext itself.
> _signerKeys | No description.

## Method Types

> Initializer
>   - init
> ASCII armor
>   - setUsesArmor:
>   - usesArmor
> Text mode
>   - setUsesTextMode:
>   - usesTextMode
> Key listing mode
>   - setKeyListMode:
>   - keyListMode
> Protocol selection
>   - setProtocol:
>   - protocol
> Passphrase delegate
>   - setPassphraseDelegate:
>   - passphraseDelegate
> Selecting signers
>   - clearSignerKeys
>   - addSignerKey:
>   - signerKeyEnumerator
>   - signerKeys
> Including certificates (S/MIME only)
>   - setCertificatesInclusion:
>   - certificatesInclusion
> Operation results
>   - operationResults
> Contextual information
>   - setUserInfo:
>   - userInfo
> Asynchronous operations (NOTE THAT ASYNCHRONOUS OPERATIONS DON'T WORK RIGHT NOW.)
>   + waitOnAnyRequest:
>   - wait:
>   - cancel
> Crypto operations
> Decrypt
>   - decryptedData:
> Verify
>   - verifySignatureData:againstData:
>   - verifySignedData:
>   - verifySignedData:originalData:
>   - signatures
> Decrypt and verify
>   - decryptedData:signatures:
> Sign
>   - signedData:signatureMode:
> Encrypt
>   - encryptedData:withKeys:trustAllKeys:
> Encrypt and Sign
>   - encryptedSignedData:withKeys:trustAllKeys:
> Symmetric Encryption (no key needed)
>   - encryptedData:
> Managing key-ring
>   - exportedKeys:
>   - importKeyData:
>   - generateKeyFromDictionary:secretKey:publicKey:
>   - deleteKey:evenIfSecretKey:
> Finding/refreshing a single key
>   - keyFromFingerprint:secretKey:
>   - refreshKey:
> Listing keys
>   - keyEnumeratorForSearchPattern:secretKeysOnly:
>   - keyEnumeratorForSearchPatterns:secretKeysOnly:
>   - stopKeyEnumeration
> Listing trust items
>   - trustItemEnumeratorForSearchPattern:maximumLevel:
>   - stopTrustItemEnumeration
> Searching keys on a key server
>   - asyncSearchForKeysMatchingPatterns:serverOptions:
>   - asyncDownloadKeys:serverOptions:
> Uploading keys on a key server
>   - asyncUploadKeys:serverOptions:
> Interrupting async operations
>   - interruptAsyncOperation
> Getting key groups
>   - keyGroups

## Class Methods

### waitOnAnyRequest:

`+ (GPGContext *)waitOnAnyRequest:(BOOL)hang`

Waits for any finished request. When hang is YES the method will wait, otherwise it will return immediately when there is no pending finished request.

Returns the context of the finished request or nil if hang is NO and no request has finished.

Can raise a GPGException which reflects the termination status of the operation (in case of error). The exception userInfo dictionary contains the context (under GPGContextKey key) which terminated with the error. An exception without any context could also be raised.

## Instance Methods

### addSignerKey:

`- (void)addSignerKey:(GPGKey *)key`

Adds key to the list of signers in the context. key is retained.

Can raise a GPGException.

### asyncDownloadKeys:serverOptions:

`- (void)asyncDownloadKeys:(NSArray *)keys serverOptions:(NSDictionary *)options`

Contacts asynchronously a key server and download keys from it. This method is usually invoked after having searched for keys on the server, and is passed a subset of keys returned by the search. Received keys are then automatically imported in default key-ring. Note that you can also pass keys from user's key-ring to refresh them.

The options dictionary can contain the following key-value pairs:

@"keyserver" | A keyserver URL, e.g. ldap://keyserver.pgp.com or x-hkp://keyserver.pgp.com:8000; if keyserver is not set, the default keyserver, from gpg configuration, is used.
@"keyserver-options" | An array which can contain the following string values: @"include-revoked", @"include-disabled", @"honor-http-proxy", @"broken-http-proxy", @"try-dns-srv" or the same options but prefixed by @"no-". If this pair is not given, values are taken from gpg configuration. Not all types of servers support all these options, but unsupported ones are silently ignored.

A GPGAsynchronousOperationDidTerminateNotification notification will be sent on completion of the operation, be it successful or not. The object is the context. See -operationResults to get imported keys.

Downloaded keys will be automatically imported in your default key-ring, and a GPGKeyringChangedNotification notification will be posted, like for an import operation. See importKeyData: for more information about this notification and how to get downloaded keys.

Method cannot be used yet to download CMS keys.

Can raise a GPGException:

GPGErrorInvalidValue | gpg is not configured correctly. More information in GPGAdditionalReasonKey userInfo key
GPGErrorGeneralError | An unknown error occurred during search. More information in GPGAdditionalReasonKey userInfo key

### asyncSearchForKeysMatchingPatterns:serverOptions:

`- (void)asyncSearchForKeysMatchingPatterns:(NSArray *)searchPatterns serverOptions:(NSDictionary *)options`

Contacts asynchronously a key server and asks it for keys matching searchPatterns.

The options dictionary can contain the following key-value pairs:

@"keyserver" | A keyserver URL, e.g. ldap://keyserver.pgp.com or x-hkp://keyserver.pgp.com:8000; if keyserver is not set, the default keyserver, from gpg configuration, is used.
@"keyserver-options" | An array which can contain the following string values: @"include-revoked", @"include-disabled", @"honor-http-proxy", @"broken-http-proxy", @"try-dns-srv" or the same options but prefixed by @"no-". If this pair is not given, values are taken from gpg configuration. Not all types of servers support all these options, but unsupported ones are silently ignored.

A GPGAsynchronousOperationDidTerminateNotification notification will be sent on completion of the operation, be it successful or not. The object is the context, and the results can be retrieved from -operationResults.

Once you got results, you can invoke asyncDownloadKeys:serverOptions: passing for example a subset of the keys returned from the search.

Method cannot be used yet to search CMS keys.

Can raise a GPGException:

GPGErrorKeyServerError | gpg is not configured correctly. More information in GPGAdditionalReasonKey userInfo key
GPGErrorGeneralError | An unknown error occurred during search. More information in GPGAdditionalReasonKey userInfo key

### asyncUploadKeys:serverOptions:

`- (void)asyncUploadKeys:(NSArray *)keys serverOptions:(NSDictionary *)options`

Contacts asynchronously a key server to uploads keys. Only public keys are uploaded: if you pass, by mistake, a secret key, method will upload the public key, not the secret one.

The options dictionary can contain the following key-value pairs:

@"keyserver" | A keyserver URL, e.g. ldap://keyserver.pgp.com or x-hkp://keyserver.pgp.com:8000; if keyserver is not set, the default keyserver, from gpg configuration, is used.
@"keyserver-options" | An array which can contain the following string values: @"include-revoked", @"include-disabled", @"honor-http-proxy", @"broken-http-proxy", @"try-dns-srv" or the same options but prefixed by @"no-". If this pair is not given, values are taken from gpg configuration. Not all types of servers support all these options, but unsupported ones are silently ignored.

A GPGAsynchronousOperationDidTerminateNotification notification will be sent on completion of the operation, be it successful or not. The object is the context, and the results can be retrieved from -operationResults.

Method cannot be used yet to search CMS keys.

Can raise a GPGException:

GPGErrorKeyServerError | gpg is not configured correctly. More information in GPGAdditionalReasonKey userInfo key
GPGErrorGeneralError | An unknown error occurred during search. More information in GPGAdditionalReasonKey userInfo key

### cancel

`- (void)cancel`

Attempts to cancel a pending operation in the context. This only works if you use the global event loop or your own event loop.

Can raise a GPGException if the cancellation failed (in this case the state of context is not modified).

### certificatesInclusion

`- (int)certificatesInclusion`

Returns the number of certificates to include in an S/MIME message.

### clearSignerKeys

`- (void)clearSignerKeys`

Remove the list of signers from the context.

Every context starts with an empty list.

### decryptedData:

`- (GPGData *)decryptedData:(GPGData *)inputData`

Decrypts the ciphertext in the inputData and returns the plain data.

Can raise a GPGException:

GPGErrorNoData | inputData does not contain any data to decrypt.
GPGErrorDecryptionFailed | inputData is not a valid cipher text.
GPGErrorBadPassphrase | The passphrase for the secret key could not be retrieved.
GPGErrorCancelled | User cancelled operation, e.g. when asked for passphrase

Others exceptions could be raised too.

### decryptedData:signatures:

`- (GPGData *)decryptedData:(GPGData *)inputData signatures:(NSArray **)signaturesPtr`

Decrypts the ciphertext in inputData and returns it as plain. If cipher contains signatures, they will be verified and returned in *signaturesPtr, if signaturesPtr is not NULL, by invoking -signatures.

With OpenPGP engine, user has 3 attempts for passphrase in case of public key encryption, else only 1 attempt.

Can raise a GPGException:

GPGErrorNoData | inputData does not contain any data to decrypt. However, it might still be signed. The information about detected signatures is available with -signatures in this case.
GPGErrorDecryptionFailed | inputData is not a valid cipher text.
GPGErrorBadPassphrase | The passphrase for the secret key could not be retrieved.
GPGErrorCancelled | User cancelled operation, e.g. when asked for passphrase

Others exceptions could be raised too.

### deleteKey:evenIfSecretKey:

`- (void)deleteKey:(GPGKey *)key evenIfSecretKey:(BOOL)allowSecret`

Deletes the given key from the standard key-ring of the crypto engine used by the context. To delete a secret key along with the public key, allowSecret must be YES, else only the public key is deleted, if that is supported.

Can raise a GPGException:

GPGErrorInvalidKey | key could not be found in the key-ring.
GPGErrorConflict | Secret key for key is available, but allowSecret is NO.

### encryptedData:

`- (GPGData *)encryptedData:(GPGData *)inputData`

Encrypts the plaintext in inputData using symmetric encryption (rather than public key encryption) and returns the ciphertext. The type of the ciphertext created is determined by the ASCII armor and text mode attributes set for the context.

Symmetrically encrypted cipher text can be deciphered with -decryptedData:. Note that in this case the crypto backend needs to retrieve a passphrase from the user. Symmetric encryption is currently only supported for the OpenPGP crypto backend.

With OpenPGP engine, only one attempt for passphrase is allowed.

Can raise a GPGException:

GPGErrorBadPassphrase | The passphrase for the symmetric key could not be retrieved.

Others exceptions could be raised too.

### encryptedData:withKeys:trustAllKeys:

`- (GPGData *)encryptedData:(GPGData *)inputData withKeys:(NSArray *)recipientKeys trustAllKeys:(BOOL)trustAllKeys`

Encrypts the plaintext in inputData with the keys and returns the ciphertext. The type of the ciphertext created is determined by the ASCII armor and text mode attributes set for the context.

The keys parameters may not be nil, nor be an empty array. It can contain GPGKey instances and GPGKeyGroup instances; you can mix them.

If the trustAllKeys parameter is set to YES, then all passed keys will be trusted, even if the keys do not have a high enough validity in the key-ring. This flag should be used with care; in general it is not a good idea to use any untrusted keys.

Can raise a GPGException:

GPGErrorUnusablePublicKey | Some recipients in keys are invalid, but not all. In this case the plaintext might be encrypted for all valid recipients and returned in -operationResults, for key @"cipher" (if this happens depends on the crypto engine). More information about the invalid recipients is available in -operationResults, under key @"keyErrors" which has a dictionary as value; that dictionary uses GPGKey instances as keys, and GPGError NSNumber instances as values.
GPGErrorGeneralError | For example, some keys were not trusted. See -operationResults, under key @"keyErrors".

Others exceptions could be raised too.

### encryptedSignedData:withKeys:trustAllKeys:

`- (GPGData *)encryptedSignedData:(GPGData *)inputData withKeys:(NSArray *)keys trustAllKeys:(BOOL)trustAllKeys`

Signs then encrypts, in one operation, the plaintext in inputData for the recipients and returns the ciphertext. The type of the ciphertext created is determined by the ASCII armor and text mode attributes set for the context. The signers are set using -addSignerKey:.

This combined encrypt and sign operation is currently only available for the OpenPGP crypto engine.

The keys can contain GPGKey instances and GPGKeyGroup instances; you can mix them.

Can raise a GPGException:

GPGErrorBadPassphrase | The passphrase for the secret key could not be retrieved.
GPGErrorUnusablePublicKey | Some recipients in keys are invalid, but not all. In this case the plaintext might be encrypted for all valid recipients and returned in -operationResults, under key @"cipher" (if this happens depends on the crypto engine). More information about the invalid recipients is available in -operationResults, under key @"keyErrors" which has a dictionary as value; that dictionary uses GPGKey instances as keys, and GPGError NSNumber instances as values.
GPGErrorUnusableSecretKey | There are invalid signers.
GPGErrorGeneralError | For example, some keys were not trusted. See -operationResults, under key @"keyErrors".

Others exceptions could be raised too.

### exportedKeys:

`- (GPGData *)exportedKeys:(NSArray *)recipientKeys`

Extracts the public key data from keys and returns them. The type of the public keys returned is determined by the ASCII armor attribute set for the context, by invoking -setUsesArmor:.

If keys is nil, then all available keys are exported.

Keys are exported from standard key-ring.

Can raise a GPGException.

### generateKeyFromDictionary:secretKey:publicKey:

`- (NSDictionary *)generateKeyFromDictionary:(NSDictionary *)params secretKey:(GPGData *)secretKeyData publicKey:(GPGData *)publicKeyData`

Generates a new key pair and puts it into the standard key-ring if both publicKeyData and secretKeyData are nil. In this case method returns immediately after starting the operation, and does not wait for it to complete. If publicKeyData is not nil, the newly created data object, upon successful completion, will contain the public key. If secretKeyData is not nil, the newly created data object, upon successful completion, will contain the secret key.

Note that not all crypto engines support this interface equally.

GnuPG does not support publicKeyData and secretKeyData, they should be both nil. GnuPG will generate a key pair and add it to the standard key-ring.

GpgSM requires publicKeyData to be a writable data object. GpgSM will generate a secret key (which will be stored by gpg-agent), and return a certificate request in public, which then needs to be signed by the certification authority and imported before it can be used.

The params dictionary specifies parameters for the key. The details about the format of params are specific to the crypto engine used by the context. Here's an example for GnuPG as the crypto engine:

@"type" | algorithm number or name
@"length" | Key NSlength in bits as a NSNumber
@"subkeyType" | NSString (ELG-E, etc.) or NSNumber. Optional.
@"subkeyLength" | Subkey length in bits as a NSNumber. Optional.
@"name" | NSString. Optional.
@"comment" | NSString. Optional.
@"email" | NSString. Optional.
@"expirationDate" | NSCalendarDate. Optional.
@"passphrase" | NSString. Optional.

Here's an example for GpgSM as the crypto engine:

@"type" | NSString (RSA, etc.) or NSNumber
@"length" | Key length in bits as a NSNumber
@"name" | NSString (C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester)
@"email" | NSString (joe@foo.bar)

Key is generated in standard secring/pubring files if both secretKeyData and publicKeyData are nil, else newly created key is returned but not stored.

See -operationResults for more information about returned dictionary.

A GPGKeyringChangedNotification notification is posted, containg the new GPGKey instances (secret and public, for OpenPGP only).

Can raise a GPGException:

GPGErrorInvalidValue | params is not a valid XML string.
GPGErrorNotSupported | publicKeyData or secretKeyData is not nil.
GPGErrorGeneralError | No key was created by the engine.

Others exceptions could be raised too.

### importKeyData:

`- (NSDictionary *)importKeyData:(GPGData *)keyData`

Adds the keys in keyData to the key-ring of the crypto engine used by the context. The format of keyData content can be ASCII armored, for example, but the details are specific to the crypto engine.

See -operationResults for information about returned dictionary.

If key-ring changed, a GPGKeyringChangedNotification notification is posted.

Can raise a GPGException:

GPGErrorNoData | keydata is an empty buffer.

Others exceptions could be raised too.

### init

`- (id)init`

Designated initializer. Creates a new context used to hold the configuration, status and result of cryptographic operations.

Can raise a GPGException; in this case, a release is sent to self.

### interruptAsyncOperation

`- (void)interruptAsyncOperation`

Interrupts asynchronous operation. The GPGAsynchronousOperationDidTerminateNotification notification will be sent with the error code GPGErrorCancelled. This method can be used to interrupt only the -async* methods. After interrupt, you can still ask the context for the operation results; you might get valid partial results. No error is returned when context is not running an async operation, or operation has already finished.

### keyEnumeratorForSearchPattern:secretKeysOnly:

`- (NSEnumerator *)keyEnumeratorForSearchPattern:(NSString *)searchPattern secretKeysOnly:(BOOL)secretKeysOnly`

Convenience method. Passing nil will return all keys. See -keyEnumeratorForSearchPatterns:secretKeysOnly:.

### keyEnumeratorForSearchPatterns:secretKeysOnly:

`- (NSEnumerator *)keyEnumeratorForSearchPatterns:(NSArray *)searchPatterns secretKeysOnly:(BOOL)secretKeysOnly`

Returns an enumerator of GPGKey instances. It starts a key listing operation inside the context; the context will be busy until either all keys are received, or -stopKeyEnumeration is invoked, or the enumerator has been deallocated.

searchPatterns is an array containing engine specific expressions that are used to limit the list to all keys matching at least one pattern. searchPatterns can be empty; in this case all keys are returned. Note that the total length of the pattern string (i.e. the length of all patterns, sometimes quoted, separated by a space character) is restricted to an engine-specific maximum (a couple of hundred characters are usually accepted). The patterns should be used to restrict the search to a certain common name or user, not to list many specific keys at once by listing their fingerprints or key IDs.

If secretKeysOnly is YES, searches only for secret keys.

This call also resets any pending key listing operation.

Can raise a GPGException, even during enumeration. Raises an exception with code GPGErrorTruncatedKeyListing during enumeration (i.e. when when invoking -nextObject on the enumerator) if the crypto backend had to truncate the result, and less than the desired keys could be listed.

### keyFromFingerprint:secretKey:

`- (GPGKey *)keyFromFingerprint:(NSString *)fingerprint secretKey:(BOOL)secretKey`

Fetches a single key, given its fingerprint (or key ID). If secretKey is YES, returns a secret key, else returns a public key. You can set the key list mode if you want to retrieve key signatures too. Returns nil if no matching key is found.

Can raise a GPGException:

GPGErrorInvalidKey | fingerprint is not a valid fingerprint, nor key ID.
GPGErrorAmbiguousName | the key ID was not a unique specifier for a key.
GPGErrorBusy | Context (self) is already performing an operation.

Others exceptions could be raised too.

### keyGroups

`- (NSArray *)keyGroups`

Returns all groups defined in gpg.conf.

### keyListMode

`- (GPGKeyListMode)keyListMode`

Returns the current key listing mode of the context. This value can then be modified and used in a subsequent setKeyListMode: invocation to only affect the desired bits (and leave all others intact).

GPGKeyListModeLocal is the default mode.

### operationResults

`- (NSDictionary *)operationResults`

Returns a dictionary containing results of last operation on context. Contents of the dictionary depends on last operation type (signing, decrypting, etc.), and method can be called even if last operation failed and raised an exception: -operationResults could return partial valid data. Dictionary always contains the result error of the last operation under key GPGErrorKey.

If last operation was an encryption operation, dictionary can contain:

@"keyErrors" | Dictionary containing GPGKey instances as keys, and GPGError NSNumber instances as values.
@"cipher" | GPGData instance with encrypted data; only valid keys were used.

If last operation was a signing operation, dictionary can contain:

@"signedData" | GPGData instance with signed data; only valid secret keys were used.
@"newSignatures" | An NSArray of GPGSignature instances.
@"keyErrors" | Dictionary containing GPGKey instances as keys, and GPGError NSNumber instances as values.

If last operation was a verification operation, dictionary can contain:

@"signatures" | An NSArray of GPGSignature instance. Same result is returned by -signatures.

If last operation was a decryption operation, dictionary can contain:

@"unsupportedAlgorithm" | An NSString instance describing the algorithm used for encryption, which is not known by the engine for decryption.
@"wrongKeyUsage" | A boolean result as a NSNumber instance indicating that the key should not have been used for encryption.

If last operation was an import operation, dictionary can contain:

@"keys" | Dictionary whose keys are GPGKey instances, and values are also dictionaries; these can contain a key-value pair 'error' with an GPGError, and a key-value pair 'status' with a GPGImportStatus (bit-field)
@"consideredKeyCount" | Total number of considered keys
@"keysWithoutUserIDCount" | Number of keys without user ID
@"importedKeyCount" | Total number of imported keys
@"importedRSAKeyCount" | Number of imported RSA keys
@"unchangedKeyCount" | Number of unchanged keys
@"newUserIDCount" | Number of new user IDs
@"newSubkeyCount" | Number of new subkeys
@"newSignatureCount" | Number of new signatures
@"newRevocationCount" | Number of new revocations
@"readSecretKeyCount" | Total number of secret keys read
@"importedSecretKeyCount" | Number of imported secret keys
@"unchangedSecretKeyCount" | Number of unchanged secret keys
@"skippedNewKeyCount" | Number of new keys skipped
@"notImportedKeyCount" | Number of keys not imported

If last operation was a key generation operation, dictionary can contain:

GPGChangesKey | See GPGKeyringChangedNotification notification for more information about GPGChangesKey.

If last operation was a key enumeration operation, dictionary can contain:

@"truncated" | A boolean result as a NSNumber instance indicating whether all matching keys were listed or not.

If last operation was a remote key search operation, dictionary can contain:

@"keys" | An array of pseudo GPGKey instances: these are not usable keys, they contain no other information than keyID, algorithmDescription, length, creationDate, expirationDate, userIDs, isKeyRevoked; userIDs are also pseudo GPGUserID instances that contain no other information than userID. Returned information depends on servers.
@"hostName" | Contacted server's host name
@"port" | Port used to contact server, if not default one
@"protocol" | Protocol used to contact server (ldap, x-hkp, hkp, http, finger)
@"options" | Options used to contact server

If last operation was a key download operation, dictionary can contain:

@"hostName" | Contacted server's host name
@"port" | Port used to contact server, if not default one
@"protocol" | Protocol used to contact server (ldap, x-hkp, hkp, http, finger)
@"options" | Options used to contact server

and additional results from the import operation.

### passphraseDelegate

`- (id)passphraseDelegate`

Returns the delegate providing the passphrase. Initially nil.

### protocol

`- (GPGProtocol)protocol`

Returns the protocol currently used by the context.

### refreshKey:

`- (GPGKey *)refreshKey:(GPGKey *)key`

Asks the engine for the key again, forcing a refresh of the key attributes. This method can be used to fetch key signatures, by setting corresponding mode in the context. A new GPGKey instance is returned; you shall no longer use the original key.

Invokes -keyFromFingerprint:secretKey:

Can raise a GPGException:

GPGErrorBusy | Context (self) is already performing an operation.

Others exceptions could be raised too.

### setCertificatesInclusion:

`- (void)setCertificatesInclusion:(int)includedCertificatesNumber`

Specifies how many certificates should be included in an S/MIME signed message. By default, only the sender's certificate is included. The possible values of includedCertificatesNumber are:

GPGAllExceptRootCertificatesInclusion | Include all certificates except the root certificate.
GPGAllCertificatesInclusion | Include all certificates.
GPGNoCertificatesInclusion | Include no certificates.
GPGOnlySenderCertificateInclusion | Include the sender's certificate only.
n | Include the first n certificates of the certificates path, starting from the sender's certificate. The number n must be positive.

Values of includedCertificatesNumber smaller than -2 are undefined.

This option is only relevant to the CMS crypto engine, and ignored by all other engines.

### setKeyListMode:

`- (void)setKeyListMode:(GPGKeyListMode)mask`

Changes the default behaviour of the key listing methods. The value in mask is a bitwise-or combination of one or multiple bit values like GPGKeyListModeLocal and GPGKeyListModeExtern.

At least GPGKeyListModeLocal or GPGKeyListModeExtern must be specified. For future binary compatibility, you should get the current mode with -keyListMode and modify it by setting or clearing the appropriate bits, and then using that calculated value in -setKeyListMode:. This will leave all other bits in the mode value intact (in particular those that are not used in the current version of the library).

Raises a GPGException with name GPGErrorInvalidValue in case mask is not a valid mode.

### setPassphraseDelegate:

`- (void)setPassphraseDelegate:(id)delegate`

This methods allows a delegate to be used to pass a passphrase to the engine. For OpenPGP, the preferred way to handle this is by using the gpg-agent, but because that beast is not ready for real use, you can use this passphrase thing.

Not all crypto engines require this callback to retrieve the passphrase. It is better if the engine retrieves the passphrase from a trusted agent (a daemon process), rather than having each user to implement their own passphrase query. Some engines do not even support an external passphrase callback at all, in this case a GPGException with error code GPGErrorNotSupported is returned.

Delegate must respond to context:passphraseForKey:again:. Delegate is not retained.

The user can disable the use of a passphrase callback by calling -setPassphraseDelegate: with nil as argument.

### setProtocol:

`- (void)setProtocol:(GPGProtocol)protocol`

Sets the protocol and thus the crypto engine to be used by the context. All crypto operations will be performed by the crypto engine configured for that protocol.

Currently, the OpenPGP and the CMS protocols are supported. A new context uses the OpenPGP engine by default.

Setting the protocol with -setProtocol: does not check if the crypto engine for that protocol is available and installed correctly.

Can raise a GPGException.

### setUserInfo:

`- (void)setUserInfo:(id)userInfo`

Sets the userInfo object, containing additional data the target may use in a callback, for example when delegate is asked for passphrase. newUserInfo is simply retained.

### setUsesArmor:

`- (void)setUsesArmor:(BOOL)armor`

Enables or disables the use of an ASCII armor for all output.

Default value is NO.

### setUsesTextMode:

`- (void)setUsesTextMode:(BOOL)mode`

Enables or disables the use of the special text mode. Text mode is for example used for MIME (RFC2015) signatures; note that the updated RFC 3156 mandates that the mail user agent does some preparations so that text mode is not needed anymore.

This option is only relevant to the OpenPGP crypto engine, and ignored by all other engines.

Default value is NO.

### signatures

`- (NSArray *)signatures`

Returns an array of GPGSignatures after -verifySignedData:, -verifySignedData:originalData:, -verifySignatureData:againstData: or -decryptedData:signatureStatus: has been called. A single detached signature can contain signatures by more than one key. Returns nil if operation was not a verification.

After -decryptedData:signatureStatus:, a GPGException with error code GPGErrorNoData counts as successful in this context.

### signedData:signatureMode:

`- (GPGData *)signedData:(GPGData *)inputData signatureMode:(GPGSignatureMode)mode`

Creates a signature for the text in inputData and returns either the signed data or a detached signature, depending on the mode. Data will be signed using either the default key (defined in engine configuration file) or the ones defined in context. The type of the signature created is determined by the ASCII armor and text mode attributes set for the context and the requested signature mode mode.

A signature can contain signatures by one or more keys. The set of keys used to create a signatures is contained in the context, and is applied to all following signing operations in the context (until the set is changed).

If an S/MIME signed message is created using the CMS crypto engine, the number of certificates to include in the message can be specified with -setIncludedCertificates:.

Note that settings done by -setUsesArmor: and -setUsesTextMode: are ignored for mode GPGSignatureModeClear.

With OpenPGP engine, user has 3 attempts for passphrase.

Can raise a GPGException:

GPGErrorNoData | The signature could not be created.
GPGErrorBadPassphrase | The passphrase for the secret key could not be retrieved.
GPGErrorUnusableSecretKey | There are invalid signers.

Others exceptions could be raised too.

### signerKeyEnumerator

`- (NSEnumerator *)signerKeyEnumerator`

Returns an enumerator of GPGKey instances, from the list of signers.

### signerKeys

`- (NSArray *)signerKeys`

Convenience method. Returns [[self signerKeyEnumerator] allObjects].

### stopKeyEnumeration

`- (void)stopKeyEnumeration`

Ends the key listing operation and allows to use the context for some other operation next. This is not an error to invoke that method if there is no pending key listing operation.

Can raise a GPGException.

### stopTrustItemEnumeration

`- (void)stopTrustItemEnumeration`

Ends the trust item listing operation and allows to use the context for some other operation next. This is not an error to invoke that method if there is no pending trust list operation.

Can raise a GPGException.

### trustItemEnumeratorForSearchPattern:maximumLevel:

`- (NSEnumerator *)trustItemEnumeratorForSearchPattern:(NSString *)searchPattern maximumLevel:(int)maxLevel`

Returns an enumerator of GPGTrustItem instances, and initiates a trust item listing operation inside the context.

searchPattern contains an engine specific expression that is used to limit the list to all trust items matching the pattern. It can not be the empty string or nil.

maxLevel is currently ignored.

Context will be busy until either all trust items are enumerated, or -stopTrustItemEnumeration is invoked, or the enumerator has been deallocated.

Can raise a GPGException, even during enumeration.

### userInfo

`- (id)userInfo`

Returns the userInfo object, containing additional data the target may use in a callback, for example when delegate is asked for passphrase.

### usesArmor

`- (BOOL)usesArmor`

Returns whether context uses ASCII armor or not. Default value is NO.

### usesTextMode

`- (BOOL)usesTextMode`

Returns whether context uses text mode or not. Default value is NO.

### verifySignatureData:againstData:

`- (NSArray *)verifySignatureData:(GPGData *)signatureData againstData:(GPGData *)inputData`

Performs a signature check on the detached signature given in signatureData (plaintext). Returns an array of GPGSignature instances, by invoking -signatures.

Can raise a GPGException:

GPGErrorNoData | inputData does not contain any data to verify.

Others exceptions could be raised too.

### verifySignedData:

`- (NSArray *)verifySignedData:(GPGData *)signedData`

Performs a signature check on signedData. This methods invokes -verifySignedData:originalData: with originalData set to NULL.

Can raise a GPGException:

GPGErrorNoData | inputData does not contain any data to verify.

Others exceptions could be raised too.

### verifySignedData:originalData:

`- (NSArray *)verifySignedData:(GPGData *)signedData originalData:(GPGData **)originalDataPtr`

Returns an array of GPGSignature instances. originalDataPtr will contain (on success) the data that has been signed. It can be NULL.

Can raise a GPGException:

GPGErrorNoData | inputData does not contain any data to verify.

Others exceptions could be raised too.

### wait:

`- (BOOL)wait:(BOOL)hang`

Continues the pending operation within the context. In particular, it ensures the data exchange between GPGME and the crypto backend and watches over the run time status of the backend process.

If hang is YES the method does not return until the operation is completed or cancelled. Otherwise the method will not block for a long time.

Returns YES if there is a finished request for context or NO if hang is NO and no request (for context) has finished.

Can raise a GPGException which reflects the termination status of the operation, in case of error.

Version 1.1 Copyright ©2005 by Mac GPG Project. All Rights Reserved. Sun Jan 23 16:54:41 2005