Back to index

lightning-sunbird  0.9+nobinonly
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  *
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *   David Drinan <>
00024  *
00025  * Alternatively, the contents of this file may be used under the terms of
00026  * either of the GNU General Public License Version 2 or later (the "GPL"),
00027  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00028  * in which case the provisions of the GPL or the LGPL are applicable instead
00029  * of those above. If you wish to allow use of your version of this file only
00030  * under the terms of either the GPL or the LGPL, and not to allow others to
00031  * use your version of this file under the terms of the MPL, indicate your
00032  * decision by deleting the provisions above and replace them with the notice
00033  * and other provisions required by the GPL or the LGPL. If you do not delete
00034  * the provisions above, a recipient may use your version of this file under
00035  * the terms of any one of the MPL, the GPL or the LGPL.
00036  *
00037  * ***** END LICENSE BLOCK ***** */
00039 #ifndef _MIMECRYP_H_
00040 #define _MIMECRYP_H_
00042 #include "mimecont.h"
00043 // #include "mimeenc.h"
00044 #include "modmimee.h"
00045 #include "mimepbuf.h"
00047 /* The MimeEncrypted class implements a type of MIME object where the object
00048    is passed to some other routine, which then returns a new MIME object.
00049    This is the basis of a decryption module.
00051    Oddly, this class behaves both as a container and as a leaf: it acts as a
00052    container in that it parses out data in order to eventually present a
00053    contained object; however, it acts as a leaf in that this container may
00054    itself have a Content-Transfer-Encoding applied to its body.  This violates
00055    the cardinal rule of MIME containers, which is that encodings don't nest,
00056    and therefore containers can't have encodings.  But, the fact that the
00057    S/MIME spec doesn't follow the groundwork laid down by previous MIME specs
00058    isn't something we can do anything about at this point...
00060    Therefore, this class duplicates some of the work done by the MimeLeaf
00061    class, to meet its dual goals of container-hood and leaf-hood.  (We could
00062    alternately have made this class be a subclass of leaf, and had it duplicate
00063    the effort of MimeContainer, but that seemed like the harder approach.)
00065    The MimeEncrypted class provides the following methods:
00067    void *crypto_init(MimeObject *obj,
00068                                     int (*output_fn) (const char *data, int32 data_size,
00069                                                                   void *output_closure),
00070                                     void *output_closure)
00072      This is called with the MimeObject representing the encrypted data.
00073         The obj->headers should be used to initialize the decryption engine.
00074         NULL indicates failure; otherwise, an opaque closure object should
00075         be returned.
00077         output_fn is what the decryption module should use to write a new MIME
00078         object (the decrypted data.)  output_closure should be passed along to
00079         every call to the output routine.
00081         The data sent to output_fn should begin with valid MIME headers indicating
00082         the type of the data.  For example, if decryption resulted in a text
00083         document, the data fed through to the output_fn might minimally look like
00085                             Content-Type: text/plain
00087                             This is the decrypted data.
00088                             It is only two lines long.
00090      Of course, the data may be of any MIME type, including multipart/mixed.
00091         Any returned MIME object will be recursively processed and presented
00092         appropriately.  (This also imples that encrypted objects may nest, and
00093         thus that the underlying decryption module must be reentrant.)
00095    int crypto_write (const char *data, int32 data_size, void *crypto_closure)
00097      This is called with the raw encrypted data.  This data might not come
00098         in line-based chunks: if there was a Content-Transfer-Encoding applied
00099         to the data (base64 or quoted-printable) then it will have been decoded
00100         first (handing binary data to the filter_fn.)  `crypto_closure' is the
00101         object that `crypto_init' returned.  This may return negative on error.
00103    int crypto_eof (void *crypto_closure, PRBool abort_p)
00105      This is called when no more data remains.  It may call `output_fn' again
00106         to flush out any buffered data.  If `abort_p' is true, then it may choose
00107         to discard any data rather than processing it, as we're terminating
00108         abnormally.
00110    char * crypto_generate_html (void *crypto_closure)
00112      This is called after `crypto_eof' but before `crypto_free'.  The crypto
00113         module should return a newly-allocated string of HTML code which
00114         explains the status of the decryption to the user (whether the signature
00115         checked out, etc.)
00117    void crypto_free (void *crypto_closure)
00119      This will be called when we're all done, after `crypto_eof' and
00120         `crypto_emit_html'.  It is intended to free any data represented
00121         by the crypto_closure.  output_fn may not be called.
00124    int (*parse_decoded_buffer) (const char *buf, int32 size, MimeObject *obj)
00126      This method, of the same name as one in MimeLeaf, is a part of the
00127         afforementioned leaf/container hybridization.  This method is invoked
00128         with the content-transfer-decoded body of this part (without line
00129         buffering.)  The default behavior of this method is to simply invoke
00130         `crypto_write' on the data with which it is called.  It's unlikely that
00131         a subclass will need to specialize this.
00132  */
00134 typedef struct MimeEncryptedClass MimeEncryptedClass;
00135 typedef struct MimeEncrypted      MimeEncrypted;
00137 struct MimeEncryptedClass {
00138   MimeContainerClass container;
00140   /* Duplicated from MimeLeaf, see comments above.
00141      This is the callback that is handed to the decoder. */
00142   int (*parse_decoded_buffer) (const char *buf, PRInt32 size, MimeObject *obj);
00145   /* Callbacks used by decryption module. */
00146   void * (*crypto_init) (MimeObject *obj,
00147                                            int (*output_fn) (const char *data, PRInt32 data_size,
00148                                                                          void *output_closure),
00149                                            void *output_closure);
00150   int (*crypto_write) (const char *data, PRInt32 data_size,
00151                                       void *crypto_closure);
00152   int (*crypto_eof) (void *crypto_closure, PRBool abort_p);
00153   char * (*crypto_generate_html) (void *crypto_closure);
00154   void (*crypto_free) (void *crypto_closure);
00155 };
00157 extern MimeEncryptedClass mimeEncryptedClass;
00159 struct MimeEncrypted {
00160   MimeContainer container;          /* superclass variables */
00161   void *crypto_closure;                    /* Opaque data used by decryption module. */
00162   MimeDecoderData *decoder_data; /* Opaque data for the Transfer-Encoding
00163                                                                decoder. */
00164   MimeHeaders *hdrs;                /* Headers of the enclosed object (including
00165                                                                the type of the *decrypted* data.) */
00166   MimePartBufferData *part_buffer; /* The data of the decrypted enclosed
00167                                                                   object (see mimepbuf.h) */
00168 };
00170 #endif /* _MIMECRYP_H_ */