/gecko_api/include/secmime.h
C++ Header | 195 lines | 22 code | 13 blank | 160 comment | 0 complexity | 52b98e37a9dd9d9fa16b5b0780c6ae7f MD5 | raw file
1/* ***** BEGIN LICENSE BLOCK ***** 2 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 3 * 4 * The contents of this file are subject to the Mozilla Public License Version 5 * 1.1 (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * http://www.mozilla.org/MPL/ 8 * 9 * Software distributed under the License is distributed on an "AS IS" basis, 10 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License 11 * for the specific language governing rights and limitations under the 12 * License. 13 * 14 * The Original Code is the Netscape security libraries. 15 * 16 * The Initial Developer of the Original Code is 17 * Netscape Communications Corporation. 18 * Portions created by the Initial Developer are Copyright (C) 1994-2000 19 * the Initial Developer. All Rights Reserved. 20 * 21 * Contributor(s): 22 * 23 * Alternatively, the contents of this file may be used under the terms of 24 * either the GNU General Public License Version 2 or later (the "GPL"), or 25 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), 26 * in which case the provisions of the GPL or the LGPL are applicable instead 27 * of those above. If you wish to allow use of your version of this file only 28 * under the terms of either the GPL or the LGPL, and not to allow others to 29 * use your version of this file under the terms of the MPL, indicate your 30 * decision by deleting the provisions above and replace them with the notice 31 * and other provisions required by the GPL or the LGPL. If you do not delete 32 * the provisions above, a recipient may use your version of this file under 33 * the terms of any one of the MPL, the GPL or the LGPL. 34 * 35 * ***** END LICENSE BLOCK ***** */ 36 37/* 38 * Header file for routines specific to S/MIME. Keep things that are pure 39 * pkcs7 out of here; this is for S/MIME policy, S/MIME interoperability, etc. 40 * 41 * $Id: secmime.h,v 1.2 2004/04/25 15:03:13 gerv%gerv.net Exp $ 42 */ 43 44#ifndef _SECMIME_H_ 45#define _SECMIME_H_ 1 46 47#include "secpkcs7.h" 48 49 50/************************************************************************/ 51SEC_BEGIN_PROTOS 52 53/* 54 * Initialize the local recording of the user S/MIME cipher preferences. 55 * This function is called once for each cipher, the order being 56 * important (first call records greatest preference, and so on). 57 * When finished, it is called with a "which" of CIPHER_FAMILID_MASK. 58 * If the function is called again after that, it is assumed that 59 * the preferences are being reset, and the old preferences are 60 * discarded. 61 * 62 * XXX This is for a particular user, and right now the storage is 63 * XXX local, static. The preference should be stored elsewhere to allow 64 * XXX for multiple uses of one library? How does SSL handle this; 65 * XXX it has something similar? 66 * 67 * - The "which" values are defined in ciferfam.h (the SMIME_* values, 68 * for example SMIME_DES_CBC_56). 69 * - If "on" is non-zero then the named cipher is enabled, otherwise 70 * it is disabled. (It is not necessary to call the function for 71 * ciphers that are disabled, however, as that is the default.) 72 * 73 * If the cipher preference is successfully recorded, SECSuccess 74 * is returned. Otherwise SECFailure is returned. The only errors 75 * are due to failure allocating memory or bad parameters/calls: 76 * SEC_ERROR_XXX ("which" is not in the S/MIME cipher family) 77 * SEC_ERROR_XXX (function is being called more times than there 78 * are known/expected ciphers) 79 */ 80extern SECStatus SECMIME_EnableCipher(long which, int on); 81 82/* 83 * Initialize the local recording of the S/MIME policy. 84 * This function is called to enable/disable a particular cipher. 85 * (S/MIME encryption or decryption using a particular cipher is only 86 * allowed if that cipher is currently enabled.) At startup, all S/MIME 87 * ciphers are disabled. From that point, this function can be called 88 * to enable a cipher -- it is not necessary to call this to disable 89 * a cipher unless that cipher was previously, explicitly enabled via 90 * this function. 91 * 92 * XXX This is for a the current module, I think, so local, static storage 93 * XXX is okay. Is that correct, or could multiple uses of the same 94 * XXX library expect to operate under different policies? 95 * 96 * - The "which" values are defined in ciferfam.h (the SMIME_* values, 97 * for example SMIME_DES_CBC_56). 98 * - If "on" is non-zero then the named cipher is enabled, otherwise 99 * it is disabled. 100 * 101 * If the cipher is successfully enabled/disabled, SECSuccess is 102 * returned. Otherwise SECFailure is returned. The only errors 103 * are due to bad parameters: 104 * SEC_ERROR_XXX ("which" is not in the S/MIME cipher family) 105 * SEC_ERROR_XXX ("which" exceeds expected maximum cipher; this is 106 * really an internal error) 107 */ 108extern SECStatus SECMIME_SetPolicy(long which, int on); 109 110/* 111 * Does the current policy allow S/MIME decryption of this particular 112 * algorithm and keysize? 113 */ 114extern PRBool SECMIME_DecryptionAllowed(SECAlgorithmID *algid, PK11SymKey *key); 115 116/* 117 * Does the current policy allow *any* S/MIME encryption (or decryption)? 118 * 119 * This tells whether or not *any* S/MIME encryption can be done, 120 * according to policy. Callers may use this to do nicer user interface 121 * (say, greying out a checkbox so a user does not even try to encrypt 122 * a message when they are not allowed to) or for any reason they want 123 * to check whether S/MIME encryption (or decryption, for that matter) 124 * may be done. 125 * 126 * It takes no arguments. The return value is a simple boolean: 127 * PR_TRUE means encryption (or decryption) is *possible* 128 * (but may still fail due to other reasons, like because we cannot 129 * find all the necessary certs, etc.; PR_TRUE is *not* a guarantee) 130 * PR_FALSE means encryption (or decryption) is not permitted 131 * 132 * There are no errors from this routine. 133 */ 134extern PRBool SECMIME_EncryptionPossible(void); 135 136/* 137 * Start an S/MIME encrypting context. 138 * 139 * "scert" is the cert for the sender. It will be checked for validity. 140 * "rcerts" are the certs for the recipients. They will also be checked. 141 * 142 * "certdb" is the cert database to use for verifying the certs. 143 * It can be NULL if a default database is available (like in the client). 144 * 145 * This function already does all of the stuff specific to S/MIME protocol 146 * and local policy; the return value just needs to be passed to 147 * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data, 148 * and finally to SEC_PKCS7DestroyContentInfo(). 149 * 150 * An error results in a return value of NULL and an error set. 151 * (Retrieve specific errors via PORT_GetError()/XP_GetError().) 152 */ 153extern SEC_PKCS7ContentInfo *SECMIME_CreateEncrypted(CERTCertificate *scert, 154 CERTCertificate **rcerts, 155 CERTCertDBHandle *certdb, 156 SECKEYGetPasswordKey pwfn, 157 void *pwfn_arg); 158 159/* 160 * Start an S/MIME signing context. 161 * 162 * "scert" is the cert that will be used to sign the data. It will be 163 * checked for validity. 164 * 165 * "certdb" is the cert database to use for verifying the cert. 166 * It can be NULL if a default database is available (like in the client). 167 * 168 * "digestalg" names the digest algorithm. (It should be SEC_OID_SHA1; 169 * XXX There should be SECMIME functions for hashing, or the hashing should 170 * be built into this interface, which we would like because we would 171 * support more smartcards that way, and then this argument should go away.) 172 * 173 * "digest" is the actual digest of the data. It must be provided in 174 * the case of detached data or NULL if the content will be included. 175 * 176 * This function already does all of the stuff specific to S/MIME protocol 177 * and local policy; the return value just needs to be passed to 178 * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data, 179 * and finally to SEC_PKCS7DestroyContentInfo(). 180 * 181 * An error results in a return value of NULL and an error set. 182 * (Retrieve specific errors via PORT_GetError()/XP_GetError().) 183 */ 184extern SEC_PKCS7ContentInfo *SECMIME_CreateSigned(CERTCertificate *scert, 185 CERTCertificate *ecert, 186 CERTCertDBHandle *certdb, 187 SECOidTag digestalg, 188 SECItem *digest, 189 SECKEYGetPasswordKey pwfn, 190 void *pwfn_arg); 191 192/************************************************************************/ 193SEC_END_PROTOS 194 195#endif /* _SECMIME_H_ */