MYCertificate Class Reference

An X.509 certificate. More...

Inherits MYKeychainItem.

Inherited by MYIdentity.

List of all members.

Public Member Functions

(id) - initWithCertificateRef:
 Initializes a MYCertificate object for an existing Keychain certificate reference.
(id) - initWithCertificateData:
 Creates a MYCertificate object from exported key data, but does not add it to any keychain.
(BOOL) - isEqualToCertificate:
 Checks whether two MYCertificate objects have bit-for-bit identical certificate data.
(SecTrustResultType) - evaluateTrust
 Determines whether the certificate is trusted for general use.
(SecTrustResultType) - evaluateTrustWithPolicy:
 Determines whether the certificate is trusted for the purpose indicated by the policy.
(BOOL) - _verify
Expert

(CSSM_CERT_TYPE) - certificateType
 The specific certificate type.
(NSArray *) - trustSettings
 Returns the full list of user-specified trust settings.
(BOOL) - setUserTrust:
 Marks a self-signed root cert as fully trusted or not trusted for all purposes.
(BOOL) - addUserTrustForPolicy:string:
 Marks a certificate as trusted by the user for a specific purpose.
(BOOL) - removeUserTrust
 Remove any user-configured trust for this certificate.

Static Public Member Functions

(MYCertificate *) + certificateWithCertificateRef:
 Creates a MYCertificate object for an existing Keychain certificate reference.
(SecPolicyRef) + X509Policy
(SecPolicyRef) + SSLPolicy
(SecPolicyRef) + SMIMEPolicy

Properties

SecCertificateRef certificateRef
 The Keychain object reference for this certificate.
NSData * certificateData
 The certificate's data.
MYPublicKeypublicKey
 The certificate's public key.
MYSHA1DigestpublicKeyDigest
 The certificate's public key's SHA-1 digest.
MYIdentityidentity
 The Identity (if any) that this Certificate is part of.
MYCertificateInfoinfo
 The metadata of the certificate, like the subject name, expiration date and capabilities.
NSString * commonName
 The common name of the subject (owner) of the certificate.
NSArray * emailAddresses
 The list (if any) of the subject's email addresses.

Mac-Only

Functionality not available on iPhone.



(NSArray *) + readCertificatesFromData:format:
 Reads multiple certificates from an aggregate file -- see the system docs for SecExternalFormat for a list of available file types.
(MYCertificate *) + preferredCertificateForName:
 Finds the current 'preferred' certificate for the given name string.
(id) - initWithCertificateData:type:encoding:
 Creates a MYCertificate object from exported key data, but does not add it to any keychain.
(BOOL) - setPreferredCertificateForName:
 Associates the receiver as the preferred certificate for the given name string.
(SecTrustSettingsResult) - userTrustSettingsForPolicy:string:
 Looks up the user-configured custom trust setings for this certificate: the ones that are accessible in apps like Keychain Access and Mail.

Detailed Description

An X.509 certificate.


Member Function Documentation

- (BOOL) addUserTrustForPolicy: (SecPolicyRef)  policy
string: (NSString*)  policyString 

Marks a certificate as trusted by the user for a specific purpose.

NOTE: This call will block while it waits for user confirmation (including an admin password).

Parameters:
policy The policy object for the type of usage (e.g. email or SSL).
policyString A policy-specific parameter. For example, SMIMEPolicy interprets this as the sender's email address, and SSLPolicy interprets it as the peer's hostname.
Returns:
YES on success, NO on failure (most likely the user canceling).
- (CSSM_CERT_TYPE) certificateType  

The specific certificate type.

Almost always CSSM_CERT_X_509v1 or CSSM_CERT_X_509v3.

+ (MYCertificate *) certificateWithCertificateRef: (SecCertificateRef)  certificateRef  

Creates a MYCertificate object for an existing Keychain certificate reference.

- (SecTrustResultType) evaluateTrust  

Determines whether the certificate is trusted for general use.

(This is really just a convenience that calls -evaluateTrustWithPolicy: using the X509Policy. If you have a specific purpose for using the certificate, it's better to call that method directly passing in the corresponding policy object.)

- (SecTrustResultType) evaluateTrustWithPolicy: (SecPolicyRef)  policy  

Determines whether the certificate is trusted for the purpose indicated by the policy.

For example, if evaluating a cert found in an email you'd use SMIMEPolicy, or for an SSL connection you'd use SSLPolicy. This does NOT consider user trust overrides, only intrinsic trust. Call -userTrustSettingsForPolicy:string: to check user trust settings.

Parameters:
policy The policy (i.e. usage) you want to evaluate. You'll generally pass the result of the class method X509Policy, SSLPolicy or SMIMEPolicy.
Returns:
kSecTrustResultProceed means the cert is trusted; kSecTrustResultUnspecified or kSecTrustResultRecoverableTrustFailure generally means the cert is (or is issued by) a self-signed root that isn't in the system trust list.
- (id) initWithCertificateData: (NSData*)  data  

Creates a MYCertificate object from exported key data, but does not add it to any keychain.

- (id) initWithCertificateData: (NSData*)  data
type: (CSSM_CERT_TYPE)  type
encoding: (CSSM_CERT_ENCODING)  encoding 

Creates a MYCertificate object from exported key data, but does not add it to any keychain.

- (id) initWithCertificateRef: (SecCertificateRef)  certificateRef  

Initializes a MYCertificate object for an existing Keychain certificate reference.

Creates a MYCertificate object for an existing Keychain certificate reference.

- (BOOL) isEqualToCertificate: (MYCertificate*)  cert  

Checks whether two MYCertificate objects have bit-for-bit identical certificate data.

(The regular -isEqual: method just calls CFEqual on the underlying SecCertificateRefs, which only tells you if they refer to the same underlying Keychain object.)

+ (MYCertificate *) preferredCertificateForName: (NSString*)  name  

Finds the current 'preferred' certificate for the given name string.

+ (NSArray *) readCertificatesFromData: (NSData*)  data
format: (SecExternalFormat)  format 

Reads multiple certificates from an aggregate file -- see the system docs for SecExternalFormat for a list of available file types.

The returned certificates are not added to a keychain. Don't use this for PKCS12 (.p12) files, because those are encrypted and include private keys as well -- for those, you should call -[MYKeychain importIdentity:].

Parameters:
data The contents of the archive file.
format The file format, if known. Typically kSecFormatPEMSequence or kSecFormatPKCS7.
Returns:
An array of MYCertificate objects.
- (BOOL) removeUserTrust  

Remove any user-configured trust for this certificate.

NOTE: This call will block while it waits for user confirmation (including an admin password).

Returns:
YES on success, NO on failure (most likely the user canceling).
- (BOOL) setPreferredCertificateForName: (NSString*)  name  

Associates the receiver as the preferred certificate for the given name string.

- (BOOL) setUserTrust: (SecTrustUserSetting)  trustSetting  

Marks a self-signed root cert as fully trusted or not trusted for all purposes.

NOTE: This call will block while it waits for user confirmation (including an admin password).

Parameters:
trustSetting Either kSecTrustResultProceed (to mark as trusted) or kSecTrustResultDeny (to mark as untrusted).
Returns:
YES on success, NO on failure (most likely the user canceling).
- (NSArray *) trustSettings  

Returns the full list of user-specified trust settings.

Returns:
An array of dictionaries; see the system docs for SecTrustSettingsCopyTrustSettings.
- (SecTrustSettingsResult) userTrustSettingsForPolicy: (SecPolicyRef)  policy
string: (NSString*)  policyString 

Looks up the user-configured custom trust setings for this certificate: the ones that are accessible in apps like Keychain Access and Mail.

Parameters:
policy The policy object indicating what you want to use this certificate for. For general-purpose use, pass X509Policy.
policyString A policy-specific parameter. For example, SMIMEPolicy interprets this as the sender's email address, and SSLPolicy interprets it as the peer's hostname.
Returns:
The trust setting. If kSecTrustSettingsResultTrustRoot or kSecTrustSettingsResultTrustAsRoot, the user has explicitly marked this cert as trusted for this policy and policyString.

Property Documentation

- (NSData *) certificateData [read, assign]

The certificate's data.

- (SecCertificateRef) certificateRef [read, assign]

The Keychain object reference for this certificate.

- (NSString *) commonName [read, assign]

The common name of the subject (owner) of the certificate.

- (NSArray *) emailAddresses [read, assign]

The list (if any) of the subject's email addresses.

- (MYIdentity *) identity [read, assign]

The Identity (if any) that this Certificate is part of.

In other words, if the matching private key is in the Keychain, this allows you to reach it.

- (MYCertificateInfo *) info [read, assign]

The metadata of the certificate, like the subject name, expiration date and capabilities.

- (MYPublicKey *) publicKey [read, assign]

The certificate's public key.

- (MYSHA1Digest *) publicKeyDigest [read, assign]

The certificate's public key's SHA-1 digest.

This is often used as a compact (20-byte) identifier for the certificate.


The documentation for this class was generated from the following files:
Generated on Sun Apr 17 12:23:58 2011 for MYCrypto by  doxygen 1.6.3