snej@8: //
snej@8: //  MYEncoder.h
snej@8: //  MYCrypto
snej@8: //
snej@8: //  Created by Jens Alfke on 1/16/08.
snej@8: //  Copyright 2008-2009 Jens Alfke. All rights reserved.
snej@8: //
snej@8: 
snej@8: #import <Foundation/Foundation.h>
snej@8: #import <Security/CMSEncoder.h>
snej@8: 
snej@8: @class MYIdentity, MYCertificate;
snej@8: 
snej@8: 
snej@8: /** Creates a CMS-formatted message from a blob of data; it can be signed and/or encrypted. */
snej@8: @interface MYEncoder : NSObject 
snej@8: {
snej@8:     @private
snej@8:     CMSEncoderRef _encoder;
snej@8:     OSStatus _error;
snej@8: }
snej@8: 
snej@8: /** A convenience method for one-shot encoding of a block of data.
snej@8:     @param data  The data that will be signed/encrypted.
snej@8:     @param signerOrNil  If non-nil, an Identity whose private key will sign the data.
snej@8:     @param recipientOrNil  If non-nil, the data will be encrypted so only the owner of this
snej@8:                 certificate can read it.
snej@8:     @param outError  On return, will be set to an NSError if something went wrong.
snej@8:     @return  The encoded data. */
snej@8: + (NSData*) encodeData: (NSData*)data
snej@8:                 signer: (MYIdentity*)signerOrNil
snej@8:              recipient: (MYCertificate*)recipientOrNil
snej@8:                  error: (NSError**)outError;
snej@8: 
snej@8: /** Initializes a new encoder.
snej@8:     You must add at least one signer or recipient. */
snej@8: - (id) init;
snej@8: 
snej@8: /** Tells the encoder to sign the content with this identity's private key.
snej@8:     (Multiple signers can be added, but this is rare.) */
snej@8: - (BOOL) addSigner: (MYIdentity*)signer;
snej@8: 
snej@8: /** Tells the encoder to encrypt the content with this recipient's public key.
snej@8:     Multiple recipients can be added; any one of them will be able to decrypt the message. */
snej@8: - (BOOL) addRecipient: (MYCertificate*)recipient;
snej@8: 
snej@8: /** The current error status of the encoder.
snej@8:     If something goes wrong with an operation, it will return NO,
snej@8:     and this property will contain the error. */
snej@8: @property (readonly) NSError* error;
snej@8: 
snej@8: /** Setting this property to YES tells the encoder not to copy the content itself into the
snej@8:     encoded message. The encodedData property will then contain only metadata, such as
snej@8:     signatures and certificates.
snej@8:     This is useful if you're working with a data format that already specifies a content
snej@8:     format: it allows you to attach the encoded data elsewhere, e.g. in a header or metadata
snej@8:     attribute. */
snej@8: @property BOOL hasDetachedContent;
snej@8: 
snej@8: /** Adds data to the encoder. You can add the entire data at once, or in bits and pieces
snej@8:     (if you're reading it from a stream). */
snej@8: - (BOOL) addData: (NSData*)data;
snej@8: 
snej@8: /** The signed/encoded output data.
snej@8:     Don't call this until after the last call to -addData:. */
snej@8: - (NSData*) encodedData;
snej@8: 
snej@8: 
snej@8: /** @name Expert
snej@8:  *  Advanced methods. 
snej@8:  */
snej@8: //@{
snej@8: 
snej@8: /** Adds a timestamp showing when the message was encoded.
snej@8:     [Unfortunately there is no system API for reading these timestamps in decoded messages...] */
snej@8: - (BOOL) addTimestamp;
snej@8: 
snej@8: /** Specifies which certificates to include in the message: none, only the signer certs,
snej@8:     or the signer certs' entire chain (the default). */
snej@8: @property CMSCertificateChainMode certificateChainMode;
snej@8: 
snej@8: /** Adds an extra certificate to the encoded data, for the recipient's use. Rarely needed. */
snej@8: - (BOOL) addSupportingCert: (MYCertificate*)supportingCert;
snej@8: 
snej@8: /** The X.509 content type of the message data. */
snej@8: @property CSSM_OID contentType;
snej@8: 
snej@8: //@}
snej@8: 
snej@8: @end