The Tor Browser / file comparison

comparison: security/nss/lib/pkcs7/secmime.h

security/nss/lib/pkcs7/secmime.h

branch
TOR_BUG_9701
changeset 15
b8a032363ba2
equal deleted inserted replaced
-1:000000000000 0:8330308b22dd
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 _SECMIME_H_
11 #define _SECMIME_H_ 1
12
13 #include "secpkcs7.h"
14
15
16 /************************************************************************/
17 SEC_BEGIN_PROTOS
18
19 /*
20 * Initialize the local recording of the user S/MIME cipher preferences.
21 * This function is called once for each cipher, the order being
22 * important (first call records greatest preference, and so on).
23 * When finished, it is called with a "which" of CIPHER_FAMILID_MASK.
24 * If the function is called again after that, it is assumed that
25 * the preferences are being reset, and the old preferences are
26 * discarded.
27 *
28 * XXX This is for a particular user, and right now the storage is
29 * XXX local, static. The preference should be stored elsewhere to allow
30 * XXX for multiple uses of one library? How does SSL handle this;
31 * XXX it has something similar?
32 *
33 * - The "which" values are defined in ciferfam.h (the SMIME_* values,
34 * for example SMIME_DES_CBC_56).
35 * - If "on" is non-zero then the named cipher is enabled, otherwise
36 * it is disabled. (It is not necessary to call the function for
37 * ciphers that are disabled, however, as that is the default.)
38 *
39 * If the cipher preference is successfully recorded, SECSuccess
40 * is returned. Otherwise SECFailure is returned. The only errors
41 * are due to failure allocating memory or bad parameters/calls:
42 * SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
43 * SEC_ERROR_XXX (function is being called more times than there
44 * are known/expected ciphers)
45 */
46 extern SECStatus SECMIME_EnableCipher(long which, int on);
47
48 /*
49 * Initialize the local recording of the S/MIME policy.
50 * This function is called to enable/disable a particular cipher.
51 * (S/MIME encryption or decryption using a particular cipher is only
52 * allowed if that cipher is currently enabled.) At startup, all S/MIME
53 * ciphers are disabled. From that point, this function can be called
54 * to enable a cipher -- it is not necessary to call this to disable
55 * a cipher unless that cipher was previously, explicitly enabled via
56 * this function.
57 *
58 * XXX This is for a the current module, I think, so local, static storage
59 * XXX is okay. Is that correct, or could multiple uses of the same
60 * XXX library expect to operate under different policies?
61 *
62 * - The "which" values are defined in ciferfam.h (the SMIME_* values,
63 * for example SMIME_DES_CBC_56).
64 * - If "on" is non-zero then the named cipher is enabled, otherwise
65 * it is disabled.
66 *
67 * If the cipher is successfully enabled/disabled, SECSuccess is
68 * returned. Otherwise SECFailure is returned. The only errors
69 * are due to bad parameters:
70 * SEC_ERROR_XXX ("which" is not in the S/MIME cipher family)
71 * SEC_ERROR_XXX ("which" exceeds expected maximum cipher; this is
72 * really an internal error)
73 */
74 extern SECStatus SECMIME_SetPolicy(long which, int on);
75
76 /*
77 * Does the current policy allow S/MIME decryption of this particular
78 * algorithm and keysize?
79 */
80 extern PRBool SECMIME_DecryptionAllowed(SECAlgorithmID *algid, PK11SymKey *key);
81
82 /*
83 * Does the current policy allow *any* S/MIME encryption (or decryption)?
84 *
85 * This tells whether or not *any* S/MIME encryption can be done,
86 * according to policy. Callers may use this to do nicer user interface
87 * (say, greying out a checkbox so a user does not even try to encrypt
88 * a message when they are not allowed to) or for any reason they want
89 * to check whether S/MIME encryption (or decryption, for that matter)
90 * may be done.
91 *
92 * It takes no arguments. The return value is a simple boolean:
93 * PR_TRUE means encryption (or decryption) is *possible*
94 * (but may still fail due to other reasons, like because we cannot
95 * find all the necessary certs, etc.; PR_TRUE is *not* a guarantee)
96 * PR_FALSE means encryption (or decryption) is not permitted
97 *
98 * There are no errors from this routine.
99 */
100 extern PRBool SECMIME_EncryptionPossible(void);
101
102 /*
103 * Start an S/MIME encrypting context.
104 *
105 * "scert" is the cert for the sender. It will be checked for validity.
106 * "rcerts" are the certs for the recipients. They will also be checked.
107 *
108 * "certdb" is the cert database to use for verifying the certs.
109 * It can be NULL if a default database is available (like in the client).
110 *
111 * This function already does all of the stuff specific to S/MIME protocol
112 * and local policy; the return value just needs to be passed to
113 * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data,
114 * and finally to SEC_PKCS7DestroyContentInfo().
115 *
116 * An error results in a return value of NULL and an error set.
117 * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
118 */
119 extern SEC_PKCS7ContentInfo *SECMIME_CreateEncrypted(CERTCertificate *scert,
120 CERTCertificate **rcerts,
121 CERTCertDBHandle *certdb,
122 SECKEYGetPasswordKey pwfn,
123 void *pwfn_arg);
124
125 /*
126 * Start an S/MIME signing context.
127 *
128 * "scert" is the cert that will be used to sign the data. It will be
129 * checked for validity.
130 *
131 * "certdb" is the cert database to use for verifying the cert.
132 * It can be NULL if a default database is available (like in the client).
133 *
134 * "digestalg" names the digest algorithm. (It should be SEC_OID_SHA1;
135 * XXX There should be SECMIME functions for hashing, or the hashing should
136 * be built into this interface, which we would like because we would
137 * support more smartcards that way, and then this argument should go away.)
138 *
139 * "digest" is the actual digest of the data. It must be provided in
140 * the case of detached data or NULL if the content will be included.
141 *
142 * This function already does all of the stuff specific to S/MIME protocol
143 * and local policy; the return value just needs to be passed to
144 * SEC_PKCS7Encode() or to SEC_PKCS7EncoderStart() to create the encoded data,
145 * and finally to SEC_PKCS7DestroyContentInfo().
146 *
147 * An error results in a return value of NULL and an error set.
148 * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
149 */
150 extern SEC_PKCS7ContentInfo *SECMIME_CreateSigned(CERTCertificate *scert,
151 CERTCertificate *ecert,
152 CERTCertDBHandle *certdb,
153 SECOidTag digestalg,
154 SECItem *digest,
155 SECKEYGetPasswordKey pwfn,
156 void *pwfn_arg);
157
158 /************************************************************************/
159 SEC_END_PROTOS
160
161 #endif /* _SECMIME_H_ */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial