1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/MYEncoder.h	Sat Jun 06 15:36:35 2009 -0700
     1.3 @@ -0,0 +1,90 @@
     1.4 +//
     1.5 +//  MYEncoder.h
     1.6 +//  MYCrypto
     1.7 +//
     1.8 +//  Created by Jens Alfke on 1/16/08.
     1.9 +//  Copyright 2008-2009 Jens Alfke. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import <Foundation/Foundation.h>
    1.13 +#import <Security/CMSEncoder.h>
    1.14 +
    1.15 +@class MYIdentity, MYCertificate;
    1.16 +
    1.17 +
    1.18 +/** Creates a CMS-formatted message from a blob of data; it can be signed and/or encrypted. */
    1.19 +@interface MYEncoder : NSObject 
    1.20 +{
    1.21 +    @private
    1.22 +    CMSEncoderRef _encoder;
    1.23 +    OSStatus _error;
    1.24 +}
    1.25 +
    1.26 +/** A convenience method for one-shot encoding of a block of data.
    1.27 +    @param data  The data that will be signed/encrypted.
    1.28 +    @param signerOrNil  If non-nil, an Identity whose private key will sign the data.
    1.29 +    @param recipientOrNil  If non-nil, the data will be encrypted so only the owner of this
    1.30 +                certificate can read it.
    1.31 +    @param outError  On return, will be set to an NSError if something went wrong.
    1.32 +    @return  The encoded data. */
    1.33 ++ (NSData*) encodeData: (NSData*)data
    1.34 +                signer: (MYIdentity*)signerOrNil
    1.35 +             recipient: (MYCertificate*)recipientOrNil
    1.36 +                 error: (NSError**)outError;
    1.37 +
    1.38 +/** Initializes a new encoder.
    1.39 +    You must add at least one signer or recipient. */
    1.40 +- (id) init;
    1.41 +
    1.42 +/** Tells the encoder to sign the content with this identity's private key.
    1.43 +    (Multiple signers can be added, but this is rare.) */
    1.44 +- (BOOL) addSigner: (MYIdentity*)signer;
    1.45 +
    1.46 +/** Tells the encoder to encrypt the content with this recipient's public key.
    1.47 +    Multiple recipients can be added; any one of them will be able to decrypt the message. */
    1.48 +- (BOOL) addRecipient: (MYCertificate*)recipient;
    1.49 +
    1.50 +/** The current error status of the encoder.
    1.51 +    If something goes wrong with an operation, it will return NO,
    1.52 +    and this property will contain the error. */
    1.53 +@property (readonly) NSError* error;
    1.54 +
    1.55 +/** Setting this property to YES tells the encoder not to copy the content itself into the
    1.56 +    encoded message. The encodedData property will then contain only metadata, such as
    1.57 +    signatures and certificates.
    1.58 +    This is useful if you're working with a data format that already specifies a content
    1.59 +    format: it allows you to attach the encoded data elsewhere, e.g. in a header or metadata
    1.60 +    attribute. */
    1.61 +@property BOOL hasDetachedContent;
    1.62 +
    1.63 +/** Adds data to the encoder. You can add the entire data at once, or in bits and pieces
    1.64 +    (if you're reading it from a stream). */
    1.65 +- (BOOL) addData: (NSData*)data;
    1.66 +
    1.67 +/** The signed/encoded output data.
    1.68 +    Don't call this until after the last call to -addData:. */
    1.69 +- (NSData*) encodedData;
    1.70 +
    1.71 +
    1.72 +/** @name Expert
    1.73 + *  Advanced methods. 
    1.74 + */
    1.75 +//@{
    1.76 +
    1.77 +/** Adds a timestamp showing when the message was encoded.
    1.78 +    [Unfortunately there is no system API for reading these timestamps in decoded messages...] */
    1.79 +- (BOOL) addTimestamp;
    1.80 +
    1.81 +/** Specifies which certificates to include in the message: none, only the signer certs,
    1.82 +    or the signer certs' entire chain (the default). */
    1.83 +@property CMSCertificateChainMode certificateChainMode;
    1.84 +
    1.85 +/** Adds an extra certificate to the encoded data, for the recipient's use. Rarely needed. */
    1.86 +- (BOOL) addSupportingCert: (MYCertificate*)supportingCert;
    1.87 +
    1.88 +/** The X.509 content type of the message data. */
    1.89 +@property CSSM_OID contentType;
    1.90 +
    1.91 +//@}
    1.92 +
    1.93 +@end