# GPGKey

> Inherits From:
>   GPGObject : NSObject

> Conforms To:
>   NSCopying

> Declared In:
>   GPGME/GPGKey.h

## Class Description

Some of the cryptographic operations require that recipients or signers are specified. This is always done by specifying the respective keys that should be used for the operation.

A GPGKey instance represents a public or secret key, but NOT both!

A key can contain several user IDs and subkeys.

GPGKey instances are returned by -[GPGContext keyEnumeratorForSearchPattern:secretKeysOnly:], -[GPGContext keyOfSignatureAtIndex:]; you should never need to instantiate objects of that class.

Two GPGKey instances are considered equal (in GPGME) if they have the same fingerprint, and are both secret or public. GPGKey instances are (currently) immutable objects.

## Defined Types

> #### Synopsis:

> `typedef enum {
> GPGValidityUnknown = 0,
> GPGValidityUndefined = 1,
> GPGValidityNever = 2,
> GPGValidityMarginal = 3,
> GPGValidityFull = 4,
> GPGValidityUltimate = 5
> } GPGValidity;`

> #### Description:

> The GPGValidity type is used to specify the validity of a user ID in a key, or for a GPGTrustItem instance. The following validities are defined:

> GPGValidityUnknown | The user ID is of unknown validity [?].
> GPGValidityUndefined | No value assigned. The validity of the user ID is undefined [q].
> GPGValidityNever | The user ID is never valid [n].
> GPGValidityMarginal | The user ID is marginally valid [m].
> GPGValidityFull | The user ID is fully valid [f].
> GPGValidityUltimate | The user ID is ultimately valid [u]. Only used for keys for which the secret key is also available.

> Don't assume that higher value means higher validity; this might change in the future.

> #### Synopsis:

> `typedef enum {
> GPG_RSAAlgorithm = 1,
> GPG_RSAEncryptOnlyAlgorithm = 2,
> GPG_RSASignOnlyAlgorithm = 3,
> GPG_ElgamalEncryptOnlyAlgorithm = 16,
> GPG_DSAAlgorithm = 17,
> GPG_EllipticCurveAlgorithm = 18,
> GPG_ECDSAAlgorithm = 19,
> GPG_ElgamalAlgorithm = 20,
> GPG_DiffieHellmanAlgorithm = 21
> }GPGPublicKeyAlgorithm;`

> #### Description:

> Public key algorithms are used for encryption, decryption, signing and verification of signatures. You can convert the numerical values to strings with GPGPublicKeyAlgorithmDescription() and GPGLocalizedPublicKeyAlgorithmDescription() for printing.

> GPG_RSAAlgorithm | RSA (Rivest, Shamir, Adleman) algorithm.
> GPG_RSAEncryptOnlyAlgorithm | Deprecated. RSA (Rivest, Shamir, Adleman) algorithm for encryption and decryption only (aka RSA-E).
> GPG_RSASignOnlyAlgorithm | Deprecated. RSA (Rivest, Shamir, Adleman) algorithm for signing and verification only (aka RSA-S).
> GPG_ElgamalEncryptOnlyAlgorithm | Elgamal (aka Elgamal-E); used specifically in GnuPG.
> GPG_DSAAlgorithm | Digital Signature Algorithm.
> GPG_EllipticCurveAlgorithm | .
> GPG_ECDSAAlgorithm | .
> GPG_ElgamalAlgorithm | Elgamal.
> GPG_DiffieHellmanAlgorithm | Encrypt or Sign.

> #### Synopsis:

> `typedef enum {
> GPG_NoAlgorithm = 0,
> GPG_IDEAAlgorithm = 1,
> GPG_TripleDESAlgorithm = 2,
> GPG_CAST5Algorithm = 3,
> GPG_BlowfishAlgorithm = 4,
> GPG_SAFER_SK128Algorithm = 5,
> GPG_DES_SKAlgorithm = 6,
> GPG_AES128Algorithm = 7,
> GPG_AES192Algorithm = 8,
> GPG_AES256Algorithm = 9,
> GPG_TwoFishAlgorithm = 10,
> GPG_SkipjackAlgorithm = 101,
> GPG_TwoFish_OldAlgorithm = 102,
> GPG_DummyAlgorithm = 110
> }GPGSymmetricKeyAlgorithm;`

> #### Description:

> Symmetric key algorithms

> GPG_NoAlgorithm | Unencrypted data
> GPG_IDEAAlgorithm | [IDEA]
> GPG_TripleDESAlgorithm | [3DES] aka 3DES or DES-EDE - 168 bit key derived from 192
> GPG_CAST5Algorithm | [CAST5] 128 bit key
> GPG_BlowfishAlgorithm | [BLOWFISH] 128 bit key, 16 rounds
> GPG_SAFER_SK128Algorithm | 13 rounds
> GPG_DES_SKAlgorithm | .
> GPG_AES128Algorithm | [AES] aka Rijndael
> GPG_AES192Algorithm | aka Rijndael 192
> GPG_AES256Algorithm | aka Rijndael 256
> GPG_TwoFishAlgorithm | [TWOFISH] twofish 256 bit
> GPG_SkipjackAlgorithm | Experimental: skipjack
> GPG_TwoFish_OldAlgorithm | Experimental: twofish 128 bit
> GPG_DummyAlgorithm | No encryption at all

> #### Synopsis:

> `typedef enum {
> GPG_NoHashAlgorithm = 0,
> GPG_MD5HashAlgorithm = 1,
> GPG_SHA_1HashAlgorithm = 2,
> GPG_RIPE_MD160HashAlgorithm = 3,
> GPG_DoubleWidthSHAHashAlgorithm = 4,
> GPG_MD2HashAlgorithm = 5,
> GPG_TIGER192HashAlgorithm = 6,
> GPG_HAVALHashAlgorithm = 7,
> GPG_SHA256HashAlgorithm = 8,
> GPG_SHA384HashAlgorithm = 9,
> GPG_SHA512HashAlgorithm = 10,
> GPG_MD4HashAlgorithm = 301,
> GPG_CRC32HashAlgorithm = 302,
> GPG_CRC32RFC1510HashAlgorithm = 303,
> GPG_CRC24RFC2440HashAlgorithm = 304,
> }GPGHashAlgorithm;`

> #### Description:

> Hash algorithms

> GPG_NoHashAlgorithm | .
> GPG_MD5HashAlgorithm | .
> GPG_SHA_1HashAlgorithm | [SHA1].
> GPG_RIPE_MD160HashAlgorithm | [RIPEMD160]
> GPG_DoubleWidthSHAHashAlgorithm | .
> GPG_MD2HashAlgorithm | .
> GPG_TIGER192HashAlgorithm | .
> GPG_HAVALHashAlgorithm | 5 pass, 160 bit.
> GPG_SHA256HashAlgorithm | .
> GPG_SHA384HashAlgorithm | .
> GPG_SHA512HashAlgorithm | .
> GPG_MD4HashAlgorithm | .
> GPG_CRC32HashAlgorithm | .
> GPG_CRC32RFC1510HashAlgorithm | .
> GPG_CRC32RFC2440HashAlgorithm | .

> #### Synopsis:

> `typedef enum {
> GPG_NoCompressionAlgorithm = 0,
> GPG_ZIPCompressionAlgorithm = 1,
> GPG_ZLIBCompressionAlgorithm = 2
> }GPGCompressionAlgorithm;`

> #### Description:

> Compression algorithms

> GPG_NoCompressionAlgorithm | No compression
> GPG_ZIPCompressionAlgorithm | [ZIP] Old zlib version (RFC1951) which is used by PGP
> GPG_ZLIBCompressionAlgorithm | [ZLIB] Default algorithm (RFC1950)

## Symbolic Constants

> #### Synopsis:

> `GPGKEY_H`

## Instance Variables

> `NSArray *_subkeys;`
> `NSArray *_userIDs;`
> `NSData *_photoData;`
> `BOOL _checkedPhotoData;`

> _subkeys | Array containing GPGSubkey instances
> _userIDs | Array containing GPGUserID instances
> _photoData | No description.
> _checkedPhotoData | No description.

## Method Types

>   - hash
>   - isEqual:
>   + formattedFingerprint:
> Public and secret keys
>   - publicKey
>   - secretKey
> Description
>   - dictionaryRepresentation
> Global key capabilities
>   - canEncrypt
>   - canSign
>   - canCertify
>   - canAuthenticate
> Main key
>   - shortKeyID
>   - keyID
>   - fingerprint
>   - formattedFingerprint
>   - algorithm
>   - algorithmDescription
>   - length
>   - creationDate
>   - expirationDate
>   - isKeyRevoked
>   - isKeyInvalid
>   - hasKeyExpired
>   - isKeyDisabled
>   - isSecret
>   - ownerTrust
>   - ownerTrustDescription
>   - issuerSerial
>   - issuerName
>   - chainID
> All subkeys
>   - subkeys
> Primary user ID information
>   - userID
>   - name
>   - email
>   - comment
>   - validity
>   - validityDescription
> All user IDs
>   - userIDs
> Supported protocol
>   - supportedProtocol
>   - supportedProtocolDescription
> Other key attributes
>   - photoData
>   - keyListMode

## Class Methods

### formattedFingerprint:

`+ (NSString *)formattedFingerprint:(NSString *)fingerprint`

Convenience method. Returns fingerprint in hex digit form, formatted like this:

XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX

or

XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX

## Instance Methods

### algorithm

`- (GPGPublicKeyAlgorithm)algorithm`

Convenience method. Returns main key algorithm. The algorithm is the crypto algorithm for which the key can be used. The value corresponds to the GPGPublicKeyAlgorithm enum values.

### algorithmDescription

`- (NSString *)algorithmDescription`

Convenience method. Returns a non-localized description of the main key algorithm.

### canAuthenticate

`- (BOOL)canAuthenticate`

Returns whether the key (i.e. one of its subkeys) can be used for authentication.

### canCertify

`- (BOOL)canCertify`

Returns whether the key (i.e. one of its subkeys) can be used to create key certificates.

### canEncrypt

`- (BOOL)canEncrypt`

Returns whether the key (i.e. one of its subkeys) can be used for encryption.

### canSign

`- (BOOL)canSign`

Returns whether the key (i.e. one of its subkeys) can be used to create data signatures.

### chainID

`- (NSString *)chainID`

Returns the X.509 chain ID that can be used to build the certificate chain (only for S/MIME).

### comment

`- (NSString *)comment`

Convenience method. Returns the primary user ID comment.

### creationDate

`- (NSCalendarDate *)creationDate`

Convenience method. Returns main key creation date. Returns nil when not available or invalid.

### dictionaryRepresentation

`- (NSDictionary *)dictionaryRepresentation`

Returns a dictionary that looks something like this:

`{
algo = 17;
created = 2000-07-13 08:35:05 -0400;
expire = 2010-07-13 08:35:05 -0400;
disabled = 0;
expired = 0;
fpr = C462FA84B8113501901020D26EF377F7BBD3B003;
invalid = 0;
keyid = 6EF377F7BBD3B003;
shortkeyid = BBD3B003;
len = 1024;
revoked = 0;
secret = 1;
issuerSerial = XX;
issuerName = XX;
chainID = XX;
ownertrust = 1;
subkeys = (
{
algo = 16;
created = 2000-07-13 08:35:06 -0400;
expire = 2010-07-13 08:35:06 -0400;
disabled = 0;
expired = 0;
fpr = "";
invalid = 0;
keyid = 5745314F70E767A9;
shortkeyid = 70E767A9;
len = 2048;
revoked = 0;
}
);
userids = (
{
comment = "Gordon Worley <redbird@mac.com>";
email = "Gordon Worley <redbird@mac.com>";
invalid = 0;
name = "Gordon Worley <redbird@mac.com>";
raw = "Gordon Worley <redbird@mac.com>";
revoked = 0;
validity = 0;
},
{
comment = "";
email = "";
invalid = 0;
name = "[image of size 2493]";
raw = "[image of size 2493]";
revoked = 0;
validity = 0;
},
{
comment = "";
email = "redbird@rbisland.cx";
invalid = 0;
name = "Gordon Worley";
raw = "Gordon Worley <redbird@rbisland.cx>";
revoked = 0;
validity = 0;
}
);
}`

### email

`- (NSString *)email`

Convenience method. Returns the primary user ID email address.

### expirationDate

`- (NSCalendarDate *)expirationDate`

Convenience method. Returns main key expiration date. Returns nil when there is none or is not available or is invalid.

### fingerprint

`- (NSString *)fingerprint`

Convenience method. Returns main key fingerprint in hex digit form.

### formattedFingerprint

`- (NSString *)formattedFingerprint`

Convenience method. Returns main key fingerprint in hex digit form, formatted like this:

XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX

or

XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX

### hasKeyExpired

`- (BOOL)hasKeyExpired`

Returns whether key is expired.

### hash

`- (unsigned)hash`

Returns hash value based on fingerprint.

### isEqual:

`- (BOOL)isEqual:(id)anObject`

Returns YES if both the receiver and anObject have the same fingerprint, are of the same class, and are both public or secret keys.

### isKeyDisabled

`- (BOOL)isKeyDisabled`

Returns whether key is disabled.

### isKeyInvalid

`- (BOOL)isKeyInvalid`

Returns whether key is invalid (e.g. due to a missing self-signature). This might have several reasons, for a example for the S/MIME backend, it will be set in during key listing if the key could not be validated due to a missing certificates or unmatched policies.

### isKeyRevoked

`- (BOOL)isKeyRevoked`

Returns whether key is revoked.

### isSecret

`- (BOOL)isSecret`

If a key is secret, than all subkeys are password-protected (i.e. are secret too), but password can be different for each subkey. A subkey cannot be secret if the key is not.

### issuerName

`- (NSString *)issuerName`

Returns the X.509 issuer name attribute of the key (only for S/MIME).

### issuerSerial

`- (NSString *)issuerSerial`

Returns the X.509 issuer serial attribute of the key (only for S/MIME).

### keyID

`- (NSString *)keyID`

Convenience method. Returns main key key ID.

### keyListMode

`- (GPGKeyListMode)keyListMode`

Returns the keylist mode that was active when the key was retrieved.

### length

`- (unsigned int)length`

Convenience method. Returns main key length, in bits.

### name

`- (NSString *)name`

Convenience method. Returns the primary user ID name.

### ownerTrust

`- (GPGValidity)ownerTrust`

Returns owner trust (only for OpenPGP).

### ownerTrustDescription

`- (NSString *)ownerTrustDescription`

Returns a localized description of the owner trust.

### photoData

`- (NSData *)photoData`

Returns data for the photo user ID, if there is one. You can create an NSImage using -[NSImage initWithData:] method.

Returns nil when there is no photo user ID.

### publicKey

`- (GPGKey *)publicKey`

If key is the public key, returns self, else returns the corresponding secret key if there is one, else nil.

### secretKey

`- (GPGKey *)secretKey`

If key is the secret key, returns self, else returns the corresponding public key if there is one, else nil.

### shortKeyID

`- (NSString *)shortKeyID`

Convenience method. Returns main key short (128 bit) key ID.

### subkeys

`- (NSArray *)subkeys`

Returns the main key, followed by other subkeys, as GPGSubkey instances.

### supportedProtocol

`- (GPGProtocol)supportedProtocol`

Returns information about the protocol supported by the key.

### supportedProtocolDescription

`- (NSString *)supportedProtocolDescription`

Returns a localized description of the supported protocol.

### userID

`- (NSString *)userID`

Convenience method. Returns the primary user ID.

### userIDs

`- (NSArray *)userIDs`

Returns the primary user ID, followed by other user IDs, as GPGUserID instances.

### validity

`- (GPGValidity)validity`

Convenience method. Returns the primary user ID validity.

### validityDescription

`- (NSString *)validityDescription`

Convenience method. Returns a localized description of the primary user ID validity.

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