smime.h (7992B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 /* 6 * Header file for routines specific to S/MIME. Keep things that are pure 7 * pkcs7 out of here; this is for S/MIME policy, S/MIME interoperability, etc. 8 */ 9 10 #ifndef _SMIME_H_ 11 #define _SMIME_H_ 1 12 13 #include "cms.h" 14 15 /************************************************************************/ 16 SEC_BEGIN_PROTOS 17 18 /* 19 * Initialize the local recording of the user S/MIME cipher preferences. 20 * This function is called once for each cipher, the order being 21 * important (first call records greatest preference, and so on). 22 * When finished, it is called with a "which" of CIPHER_FAMILID_MASK. 23 * If the function is called again after that, it is assumed that 24 * the preferences are being reset, and the old preferences are 25 * discarded. 26 * 27 * This is for a particular user, and right now the storage is 28 * local, static. SSL uses the same technique, but keeps a copy in 29 * the ssl session, which can be changed to affect that particular 30 * ssl session. SSL also allows model sessions, which can be used 31 * to clone SSL configuration information to child sessions. A future 32 * version of this function could take a S/MIME content structure and 33 * affect only the given S/MIME operation. This function would still 34 * affect the default values. 35 * 36 * - The "which" still understands values which are defined in 37 * ciferfam.h (the SMIME_* values, for example SMIME_DES_CBC_56), 38 * but the preferred usage is to handle values based on algtags. 39 * - If "on" is non-zero then the named cipher is enabled, otherwise 40 * it is disabled. (It is not necessary to call the function for 41 * ciphers that are disabled, however, as that is the default.) 42 * 43 * If the cipher preference is successfully recorded, SECSuccess 44 * is returned. Otherwise SECFailure is returned. The only errors 45 * are due to failure allocating memory or bad parameters/calls: 46 * SEC_ERROR_XXX ("which" is not in the S/MIME cipher family) 47 * SEC_ERROR_XXX (function is being called more times than there 48 * are known/expected ciphers) 49 */ 50 extern SECStatus NSS_SMIMEUtil_EnableCipher(long which, int on); 51 52 /* 53 * returns the current state of a particulare encryption algorithm 54 */ 55 PRBool NSS_SMIMEUtil_EncryptionEnabled(int which); 56 57 /* 58 * Initialize the local recording of the S/MIME policy. 59 * This function is called to allow/disallow a particular cipher by 60 * policy. It uses the underlying NSS policy system. This can be used 61 * to allow new algorithms that can then be turned by 62 * NSS_SMIMEUtil_EnableCipher. 63 * 64 * - The "which" still understands values which are defined in 65 * ciferfam.h (the SMIME_* values, for example SMIME_DES_CBC_56), 66 * but the preferred usage is to handle values based on algtags. 67 * - If "on" is non-zero then the named cipher is enabled, otherwise 68 * it is disabled. 69 */ 70 extern SECStatus NSS_SMIMEUtils_AllowCipher(long which, int on); 71 72 /* 73 * Does the current policy allow S/MIME decryption of this particular 74 * algorithm and keysize? 75 */ 76 extern PRBool NSS_SMIMEUtil_DecryptionAllowed(SECAlgorithmID *algid, PK11SymKey *key); 77 78 /* 79 * Does the current policy allow S/MIME encryption of this particular 80 * algorithm and key size? 81 */ 82 extern PRBool NSS_SMIMEUtil_EncryptionAllowed(SECAlgorithmID *algid, PK11SymKey *key); 83 84 /* 85 * Does the current policy allow *any* S/MIME encryption (or decryption)? 86 * 87 * This tells whether or not *any* S/MIME encryption can be done, 88 * according to policy. Callers may use this to do nicer user interface 89 * (say, greying out a checkbox so a user does not even try to encrypt 90 * a message when they are not allowed to) or for any reason they want 91 * to check whether S/MIME encryption (or decryption, for that matter) 92 * may be done. 93 * 94 * It takes no arguments. The return value is a simple boolean: 95 * PR_TRUE means encryption (or decryption) is *possible* 96 * (but may still fail due to other reasons, like because we cannot 97 * find all the necessary certs, etc.; PR_TRUE is *not* a guarantee) 98 * PR_FALSE means encryption (or decryption) is not permitted 99 * 100 * There are no errors from this routine. 101 */ 102 extern PRBool NSS_SMIMEUtil_EncryptionPossible(void); 103 104 /* 105 * Does the current policy allow S/MIME signing with this particular 106 * algorithm? 107 */ 108 extern PRBool NSS_SMIMEUtil_SigningAllowed(SECAlgorithmID *algid); 109 110 /* 111 * Does the current policy allow S/MIME Key exchange (encrypt) of this particular 112 * algorithm and keysize? 113 */ 114 extern PRBool NSS_SMIMEUtil_KeyEncodingAllowed(SECAlgorithmID *algtag, 115 CERTCertificate *cert, SECKEYPublicKey *key); 116 117 /* 118 * Does the current policy allow S/MIME Key exchange (decrypt) of this particular 119 * algorithm and keysize? 120 */ 121 extern PRBool NSS_SMIMEUtil_KeyDecodingAllowed(SECAlgorithmID *algtag, 122 SECKEYPrivateKey *key); 123 124 /* 125 * NSS_SMIME_EncryptionPossible - check if any encryption is allowed 126 * 127 * This tells whether or not *any* S/MIME encryption can be done, 128 * according to policy. Callers may use this to do nicer user interface 129 * (say, greying out a checkbox so a user does not even try to encrypt 130 * a message when they are not allowed to) or for any reason they want 131 * to check whether S/MIME encryption (or decryption, for that matter) 132 * may be done. 133 * 134 * It takes no arguments. The return value is a simple boolean: 135 * PR_TRUE means encryption (or decryption) is *possible* 136 * (but may still fail due to other reasons, like because we cannot 137 * find all the necessary certs, etc.; PR_TRUE is *not* a guarantee) 138 * PR_FALSE means encryption (or decryption) is not permitted 139 * 140 * There are no errors from this routine. 141 */ 142 extern PRBool NSS_SMIMEUtil_EncryptionPossible(void); 143 144 /* 145 * NSS_SMIMEUtil_CreateSMIMECapabilities - get S/MIME capabilities attr value 146 * 147 * scans the list of allowed and enabled ciphers and construct a PKCS9-compliant 148 * S/MIME capabilities attribute value. 149 */ 150 extern SECStatus NSS_SMIMEUtil_CreateSMIMECapabilities(PLArenaPool *poolp, SECItem *dest); 151 152 /* 153 * NSS_SMIMEUtil_CreateSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value 154 */ 155 extern SECStatus NSS_SMIMEUtil_CreateSMIMEEncKeyPrefs(PLArenaPool *poolp, 156 SECItem *dest, CERTCertificate *cert); 157 158 /* 159 * NSS_SMIMEUtil_CreateMSSMIMEEncKeyPrefs - create S/MIME encryption key preferences attr value using MS oid 160 */ 161 extern SECStatus NSS_SMIMEUtil_CreateMSSMIMEEncKeyPrefs(PLArenaPool *poolp, 162 SECItem *dest, CERTCertificate *cert); 163 164 /* 165 * NSS_SMIMEUtil_GetCertFromEncryptionKeyPreference - find cert marked by EncryptionKeyPreference 166 * attribute 167 */ 168 extern CERTCertificate *NSS_SMIMEUtil_GetCertFromEncryptionKeyPreference(CERTCertDBHandle *certdb, 169 SECItem *DERekp); 170 171 /* 172 * NSS_SMIMEUtil_FindBulkAlgForRecipients - find bulk algorithm suitable for all recipients 173 */ 174 extern SECStatus 175 NSS_SMIMEUtil_FindBulkAlgForRecipients(CERTCertificate **rcerts, 176 SECOidTag *bulkalgtag, int *keysize); 177 178 /* 179 * Return a boolean that indicates whether the underlying library 180 * will perform as the caller expects. 181 * 182 * The only argument is a string, which should be the version 183 * identifier of the NSS library. That string will be compared 184 * against a string that represents the actual build version of 185 * the S/MIME library. 186 */ 187 extern PRBool NSSSMIME_VersionCheck(const char *importedVersion); 188 189 /* 190 * Returns a const string of the S/MIME library version. 191 */ 192 extern const char *NSSSMIME_GetVersion(void); 193 194 /************************************************************************/ 195 SEC_END_PROTOS 196 197 #endif /* _SECMIME_H_ */