5 // Created by Jens Alfke on 1/16/08.
6 // Copyright 2008 Jens Alfke. All rights reserved.
9 #import <Cocoa/Cocoa.h>
10 #import <Security/CMSDecoder.h>
12 @class MYKeychain, MYCertificate;
15 /** Decodes a CMS-formatted message into the original data, and identifies & verifies signatures. */
16 @interface MYDecoder : NSObject
19 CMSDecoderRef _decoder;
24 /** Initializes a new decoder. */
27 /** Initializes a new decoder and reads the entire message data. */
28 - (id) initWithData: (NSData*)data error: (NSError**)outError;
30 /** Specifies a keychain to use to look up certificates and keys, instead of the default
31 keychain search path. */
32 - (BOOL) useKeychain: (MYKeychain*)keychain;
34 /** Adds data to the decoder. You can add the entire data at once, or in bits and pieces
35 (if you're reading it from a stream). */
36 - (BOOL) addData: (NSData*)data;
38 /** The error, if any, that occurred while decoding the content.
39 If -addData: returns NO, read this property to find out what went wrong.
40 The most likely error is (NSOSStatusErrorDomain, errSecUnknownFormat). */
41 @property (readonly) NSError *error;
43 /** If the message content is detached (stored separately from the encoded message),
44 you must copy it to this property before calling -finish, so that the decoder can use it
45 to verify signatures. */
46 @property (retain) NSData *detachedContent;
48 /** Tells the decoder that all of the data has been read, after the last call to -addData:.
49 You must call this before accessing the message content or metadata. */
52 /** The decoded message content. */
53 @property (readonly) NSData* content;
55 /** YES if the message was signed. (Use the signers property to see who signed it.) */
56 @property (readonly) BOOL isSigned;
58 /** YES if the message was encrypted. */
59 @property (readonly) BOOL isEncrypted;
61 /** An array of MYSigner objects representing the identities who signed the message.
62 Nil if the message is unsigned. */
63 @property (readonly) NSArray* signers;
65 /** All of the certificates (as MYCertificate objects) that were attached to the message. */
66 @property (readonly) NSArray* certificates;
74 /** The X.509 content-type of the message contents.
75 The Data field points to autoreleased memory: do not free it yourself, and do not
76 expect it to remain valid after the calling method returns. */
77 @property (readonly) CSSM_OID contentType;
79 /** The Policy that will be used to evaluate trust when calling MYSigner.copyTrust.
81 @property (assign) SecPolicyRef policy;
83 /** Returns a string with detailed information about the message metadata.
84 Not user-presentable; used for debugging. */
92 /** Represents a signer of a CMS message, as returned by the MYDecoder.signers property. */
93 @interface MYSigner : NSObject
96 CMSDecoderRef _decoder;
99 CMSSignerStatus _status;
100 OSStatus _verifyResult;
104 /** The status of the signature, i.e. whether it's valid or not.
106 * kCMSSignerValid :both signature and signer certificate verified OK.
107 * kCMSSignerNeedsDetachedContent:the MYDecoder's detachedContent property must be set,
108 * to ascertain the signature status.
109 * kCMSSignerInvalidSignature :bad signature -- either the content or the signature
110 * data were tampered with after the message was encoded.
111 * kCMSSignerInvalidCert :an error occurred verifying the signer's certificate.
112 * Further information available via the verifyResult
113 * and copyTrust methods.
115 @property (readonly) CMSSignerStatus status;
117 /** The signer's certificate.
118 You should check the status property first, to see whether the signature and certificate
120 For safety purposes, if you haven't checked status yet, this method will return nil
121 if the signer status is not kCMSSignerValid. */
122 @property (readonly) MYCertificate *certificate;
124 /** The signer's email address (if any), as stored in the certificate. */
125 @property (readonly) NSString* emailAddress;
132 /** Returns the SecTrustRef that was used to verify the certificate.
133 You can use this object to get more detailed information about how the verification was done.
134 If you set the parent decoder's policy property, then that SecPolicy will be used to evaluate
135 trust; otherwise you'll need to do it yourself using the SecTrust object.
136 You must CFRelease the result when you're finished with it. */
137 - (SecTrustRef) trust;
139 /** The result of certificate verification, as a CSSM_RESULT code;
140 * a nonzero value indicates an error.
142 * Some of the most common and interesting errors are:
144 * CSSMERR_TP_INVALID_ANCHOR_CERT : The cert was verified back to a
145 * self-signed (root) cert which was present in the message, but
146 * that root cert is not a known, trusted root cert.
147 * CSSMERR_TP_NOT_TRUSTED: The cert could not be verified back to
149 * CSSMERR_TP_VERIFICATION_FAILURE: A root cert was found which does
151 * CSSMERR_TP_VERIFY_ACTION_FAILED: Indicates a failure of the requested
153 * CSSMERR_TP_INVALID_CERTIFICATE: Indicates a bad leaf cert.
154 * CSSMERR_TP_CERT_EXPIRED: A cert in the chain was expired at the time of
156 * CSSMERR_TP_CERT_NOT_VALID_YET: A cert in the chain was not yet valie at
157 * the time of verification.
159 @property (readonly) OSStatus verifyResult;
167 /** Returned from MYSigner.status to indicate a failure (non-noErr return value)
168 of the underlying CMSDecoderCopySignerStatus call. Should never occur. */
169 kMYSignerStatusCheckFailed = 666