The Tor Browser: security/nss/lib/pkcs7/secmime.h@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     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/. */

     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  */

    10 #ifndef _SECMIME_H_

    11 #define _SECMIME_H_ 1

    13 #include "secpkcs7.h"

    16 /************************************************************************/

    17 SEC_BEGIN_PROTOS

    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);

    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);

    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);

    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);

   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);

   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);

   158 /************************************************************************/

   159 SEC_END_PROTOS

   161 #endif /* _SECMIME_H_ */

The Tor Browser / file revision