- Inherits From:
- GPGObject : NSObject
- Declared In:
- GPGME/GPGContext.h
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.
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
Synopsis:
GPGCONTEXT_H
Synopsis:
GPGKeyListModeLocal 1
GPGKeyListModeExtern 2
GPGKeyListModeSignatures 4
GPGKeyListModeValidate 256
Synopsis:
GPGImportNewKeyMask 1
GPGImportNewUserIDMask 2
GPGImportSignatureMask 4
GPGImportSubkeyMask 8
GPGImportSecretKeyMask 16
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:
current/total = 100/100 may be used to detect the end of operation.
@"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.
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
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.
InitializerASCII armor
- - init
Text mode
- - setUsesArmor:
- - usesArmor
Key listing mode
- - setUsesTextMode:
- - usesTextMode
Protocol selection
- - setKeyListMode:
- - keyListMode
Passphrase delegate
- - setProtocol:
- - protocol
Selecting signers
- - setPassphraseDelegate:
- - passphraseDelegate
Including certificates (S/MIME only)
- - clearSignerKeys
- - addSignerKey:
- - signerKeyEnumerator
- - signerKeys
Operation results
- - setCertificatesInclusion:
- - certificatesInclusion
Contextual information
- - operationResults
Asynchronous operations (NOTE THAT ASYNCHRONOUS OPERATIONS DON'T WORK RIGHT NOW.)
- - setUserInfo:
- - userInfo
Crypto operations
- + waitOnAnyRequest:
- - wait:
- - cancel
Decrypt
Verify
- - decryptedData:
Decrypt and verify
- - verifySignatureData:againstData:
- - verifySignedData:
- - verifySignedData:originalData:
- - signatures
Sign
- - decryptedData:signatures:
Encrypt
- - signedData:signatureMode:
Encrypt and Sign
- - encryptedData:withKeys:trustAllKeys:
Symmetric Encryption (no key needed)
- - encryptedSignedData:withKeys:trustAllKeys:
Managing key-ring
- - encryptedData:
Finding/refreshing a single key
- - exportedKeys:
- - importKeyData:
- - generateKeyFromDictionary:secretKey:publicKey:
- - deleteKey:evenIfSecretKey:
Listing keys
- - keyFromFingerprint:secretKey:
- - refreshKey:
Listing trust items
- - keyEnumeratorForSearchPattern:secretKeysOnly:
- - keyEnumeratorForSearchPatterns:secretKeysOnly:
- - stopKeyEnumeration
Searching keys on a key server
- - trustItemEnumeratorForSearchPattern:maximumLevel:
- - stopTrustItemEnumeration
Uploading keys on a key server
- - asyncSearchForKeysMatchingPatterns:serverOptions:
- - asyncDownloadKeys:serverOptions:
Interrupting async operations
- - asyncUploadKeys:serverOptions:
Getting key groups
- - interruptAsyncOperation
- - keyGroups
+ (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.
- (void)addSignerKey:(GPGKey *)key
Adds key to the list of signers in the context. key is retained.
Can raise a GPGException.
- (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 |
- (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 |
- (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 |
- (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).
- (int)certificatesInclusion
Returns the number of certificates to include in an S/MIME message.
- (void)clearSignerKeys
Remove the list of signers from the context.
Every context starts with an empty list.
- (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 |
- (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 |
- (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. |
- (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. |
- (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". |
- (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". |
- (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.
- (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. |
| @"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) |
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. |
- (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. |
- (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.
- (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.
- (NSEnumerator *)keyEnumeratorForSearchPattern:(NSString *)searchPattern secretKeysOnly:(BOOL)secretKeysOnly
Convenience method. Passing nil will return all keys. See -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.
- (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. |
- (NSArray *)keyGroups
Returns all groups defined in gpg.conf.
- (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.
- (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 |
- (id)passphraseDelegate
Returns the delegate providing the passphrase. Initially nil.
- (GPGProtocol)protocol
Returns the protocol currently used by the context.
- (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. |
- (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.
- (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.
- (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.
- (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.
- (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.
- (void)setUsesArmor:(BOOL)armor
Enables or disables the use of an ASCII armor for all output.
Default value is NO.
- (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.
- (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.
- (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. |
- (NSEnumerator *)signerKeyEnumerator
Returns an enumerator of GPGKey instances, from the list of signers.
- (NSArray *)signerKeys
Convenience method. Returns [[self signerKeyEnumerator] allObjects].
- (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.
- (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.
- (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.
- (id)userInfo
Returns the userInfo object, containing additional data the target may use in a callback, for example when delegate is asked for passphrase.
- (BOOL)usesArmor
Returns whether context uses ASCII armor or not. Default value is NO.
- (BOOL)usesTextMode
Returns whether context uses text mode or not. Default value is NO.
- (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. |
- (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. |
- (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. |
- (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.