snej@8
|
1 |
//
|
snej@8
|
2 |
// MYEncoder.h
|
snej@8
|
3 |
// MYCrypto
|
snej@8
|
4 |
//
|
snej@8
|
5 |
// Created by Jens Alfke on 1/16/08.
|
snej@8
|
6 |
// Copyright 2008-2009 Jens Alfke. All rights reserved.
|
snej@8
|
7 |
//
|
snej@8
|
8 |
|
snej@8
|
9 |
#import <Foundation/Foundation.h>
|
snej@8
|
10 |
#import <Security/CMSEncoder.h>
|
snej@8
|
11 |
|
snej@8
|
12 |
@class MYIdentity, MYCertificate;
|
snej@8
|
13 |
|
snej@8
|
14 |
|
snej@8
|
15 |
/** Creates a CMS-formatted message from a blob of data; it can be signed and/or encrypted. */
|
snej@8
|
16 |
@interface MYEncoder : NSObject
|
snej@8
|
17 |
{
|
snej@8
|
18 |
@private
|
snej@8
|
19 |
CMSEncoderRef _encoder;
|
snej@8
|
20 |
OSStatus _error;
|
snej@8
|
21 |
}
|
snej@8
|
22 |
|
snej@8
|
23 |
/** A convenience method for one-shot encoding of a block of data.
|
snej@8
|
24 |
@param data The data that will be signed/encrypted.
|
snej@8
|
25 |
@param signerOrNil If non-nil, an Identity whose private key will sign the data.
|
snej@8
|
26 |
@param recipientOrNil If non-nil, the data will be encrypted so only the owner of this
|
snej@8
|
27 |
certificate can read it.
|
snej@8
|
28 |
@param outError On return, will be set to an NSError if something went wrong.
|
snej@8
|
29 |
@return The encoded data. */
|
snej@8
|
30 |
+ (NSData*) encodeData: (NSData*)data
|
snej@8
|
31 |
signer: (MYIdentity*)signerOrNil
|
snej@8
|
32 |
recipient: (MYCertificate*)recipientOrNil
|
snej@8
|
33 |
error: (NSError**)outError;
|
snej@8
|
34 |
|
snej@8
|
35 |
/** Initializes a new encoder.
|
snej@8
|
36 |
You must add at least one signer or recipient. */
|
snej@8
|
37 |
- (id) init;
|
snej@8
|
38 |
|
snej@8
|
39 |
/** Tells the encoder to sign the content with this identity's private key.
|
snej@8
|
40 |
(Multiple signers can be added, but this is rare.) */
|
snej@8
|
41 |
- (BOOL) addSigner: (MYIdentity*)signer;
|
snej@8
|
42 |
|
snej@8
|
43 |
/** Tells the encoder to encrypt the content with this recipient's public key.
|
snej@8
|
44 |
Multiple recipients can be added; any one of them will be able to decrypt the message. */
|
snej@8
|
45 |
- (BOOL) addRecipient: (MYCertificate*)recipient;
|
snej@8
|
46 |
|
snej@8
|
47 |
/** The current error status of the encoder.
|
snej@8
|
48 |
If something goes wrong with an operation, it will return NO,
|
snej@8
|
49 |
and this property will contain the error. */
|
snej@8
|
50 |
@property (readonly) NSError* error;
|
snej@8
|
51 |
|
snej@8
|
52 |
/** Setting this property to YES tells the encoder not to copy the content itself into the
|
snej@8
|
53 |
encoded message. The encodedData property will then contain only metadata, such as
|
snej@8
|
54 |
signatures and certificates.
|
snej@8
|
55 |
This is useful if you're working with a data format that already specifies a content
|
snej@8
|
56 |
format: it allows you to attach the encoded data elsewhere, e.g. in a header or metadata
|
snej@8
|
57 |
attribute. */
|
snej@8
|
58 |
@property BOOL hasDetachedContent;
|
snej@8
|
59 |
|
snej@8
|
60 |
/** Adds data to the encoder. You can add the entire data at once, or in bits and pieces
|
snej@8
|
61 |
(if you're reading it from a stream). */
|
snej@8
|
62 |
- (BOOL) addData: (NSData*)data;
|
snej@8
|
63 |
|
snej@8
|
64 |
/** The signed/encoded output data.
|
snej@8
|
65 |
Don't call this until after the last call to -addData:. */
|
snej@8
|
66 |
- (NSData*) encodedData;
|
snej@8
|
67 |
|
snej@8
|
68 |
|
snej@8
|
69 |
/** @name Expert
|
snej@8
|
70 |
* Advanced methods.
|
snej@8
|
71 |
*/
|
snej@8
|
72 |
//@{
|
snej@8
|
73 |
|
snej@8
|
74 |
/** Adds a timestamp showing when the message was encoded.
|
snej@8
|
75 |
[Unfortunately there is no system API for reading these timestamps in decoded messages...] */
|
snej@8
|
76 |
- (BOOL) addTimestamp;
|
snej@8
|
77 |
|
snej@8
|
78 |
/** Specifies which certificates to include in the message: none, only the signer certs,
|
snej@8
|
79 |
or the signer certs' entire chain (the default). */
|
snej@8
|
80 |
@property CMSCertificateChainMode certificateChainMode;
|
snej@8
|
81 |
|
snej@8
|
82 |
/** Adds an extra certificate to the encoded data, for the recipient's use. Rarely needed. */
|
snej@8
|
83 |
- (BOOL) addSupportingCert: (MYCertificate*)supportingCert;
|
snej@8
|
84 |
|
snej@8
|
85 |
/** The X.509 content type of the message data. */
|
snej@8
|
86 |
@property CSSM_OID contentType;
|
snej@8
|
87 |
|
snej@8
|
88 |
//@}
|
snej@8
|
89 |
|
snej@8
|
90 |
@end
|