Back to index

lightning-sunbird  0.9+nobinonly
secpkcs7.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 /*
00038  * Interface to the PKCS7 implementation.
00039  *
00040  * $Id: secpkcs7.h,v 1.5 2004/04/25 15:03:13 gerv%gerv.net Exp $
00041  */
00042 
00043 #ifndef _SECPKCS7_H_
00044 #define _SECPKCS7_H_
00045 
00046 #include "seccomon.h"
00047 
00048 #include "secoidt.h"
00049 #include "certt.h"
00050 #include "keyt.h"
00051 #include "hasht.h"
00052 #include "pkcs7t.h"
00053 
00054 extern const SEC_ASN1Template sec_PKCS7ContentInfoTemplate[];
00055 
00056 /************************************************************************/
00057 SEC_BEGIN_PROTOS
00058 
00059 /************************************************************************
00060  *     Miscellaneous
00061  ************************************************************************/
00062 
00063 /*
00064  * Returns the content type of the given contentInfo.
00065  */
00066 extern SECOidTag SEC_PKCS7ContentType (SEC_PKCS7ContentInfo *cinfo);
00067 
00068 /*
00069  * Destroy a PKCS7 contentInfo and all of its sub-pieces.
00070  */
00071 extern void SEC_PKCS7DestroyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
00072 
00073 /*
00074  * Copy a PKCS7 contentInfo.  A Destroy is needed on *each* copy.
00075  */
00076 extern SEC_PKCS7ContentInfo *
00077 SEC_PKCS7CopyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
00078 
00079 /*
00080  * Return a pointer to the actual content.  In the case of those types
00081  * which are encrypted, this returns the *plain* content.
00082  */
00083 extern SECItem *SEC_PKCS7GetContent(SEC_PKCS7ContentInfo *cinfo);
00084 
00085 /************************************************************************
00086  *     PKCS7 Decoding, Verification, etc..
00087  ************************************************************************/
00088 
00089 extern SEC_PKCS7DecoderContext *
00090 SEC_PKCS7DecoderStart(SEC_PKCS7DecoderContentCallback callback,
00091                     void *callback_arg,
00092                     SECKEYGetPasswordKey pwfn, void *pwfn_arg,
00093                     SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, 
00094                     void *decrypt_key_cb_arg,
00095                     SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
00096 
00097 extern SECStatus
00098 SEC_PKCS7DecoderUpdate(SEC_PKCS7DecoderContext *p7dcx,
00099                      const char *buf, unsigned long len);
00100 
00101 extern SEC_PKCS7ContentInfo *
00102 SEC_PKCS7DecoderFinish(SEC_PKCS7DecoderContext *p7dcx);
00103 
00104 
00105 /*  Abort the underlying ASN.1 stream & set an error  */
00106 void SEC_PKCS7DecoderAbort(SEC_PKCS7DecoderContext *p7dcx, int error);
00107 
00108 extern SEC_PKCS7ContentInfo *
00109 SEC_PKCS7DecodeItem(SECItem *p7item,
00110                   SEC_PKCS7DecoderContentCallback cb, void *cb_arg,
00111                   SECKEYGetPasswordKey pwfn, void *pwfn_arg,
00112                   SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, 
00113                   void *decrypt_key_cb_arg,
00114                   SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
00115 
00116 extern PRBool SEC_PKCS7ContainsCertsOrCrls(SEC_PKCS7ContentInfo *cinfo);
00117 
00118 /* checks to see if the contents of the content info is
00119  * empty.  it so, PR_TRUE is returned.  PR_FALSE, otherwise.
00120  *
00121  * minLen is used to specify a minimum size.  if content size <= minLen,
00122  * content is assumed empty.
00123  */
00124 extern PRBool 
00125 SEC_PKCS7IsContentEmpty(SEC_PKCS7ContentInfo *cinfo, unsigned int minLen); 
00126 
00127 extern PRBool SEC_PKCS7ContentIsEncrypted(SEC_PKCS7ContentInfo *cinfo);
00128 
00129 /*
00130  * If the PKCS7 content has a signature (not just *could* have a signature)
00131  * return true; false otherwise.  This can/should be called before calling
00132  * VerifySignature, which will always indicate failure if no signature is
00133  * present, but that does not mean there even was a signature!
00134  * Note that the content itself can be empty (detached content was sent
00135  * another way); it is the presence of the signature that matters.
00136  */
00137 extern PRBool SEC_PKCS7ContentIsSigned(SEC_PKCS7ContentInfo *cinfo);
00138 
00139 /*
00140  * SEC_PKCS7VerifySignature
00141  *     Look at a PKCS7 contentInfo and check if the signature is good.
00142  *     The verification checks that the signing cert is valid and trusted
00143  *     for the purpose specified by "certusage".
00144  *
00145  *     In addition, if "keepcerts" is true, add any new certificates found
00146  *     into our local database.
00147  */
00148 extern PRBool SEC_PKCS7VerifySignature(SEC_PKCS7ContentInfo *cinfo,
00149                                    SECCertUsage certusage,
00150                                    PRBool keepcerts);
00151 
00152 /*
00153  * SEC_PKCS7VerifyDetachedSignature
00154  *     Look at a PKCS7 contentInfo and check if the signature matches
00155  *     a passed-in digest (calculated, supposedly, from detached contents).
00156  *     The verification checks that the signing cert is valid and trusted
00157  *     for the purpose specified by "certusage".
00158  *
00159  *     In addition, if "keepcerts" is true, add any new certificates found
00160  *     into our local database.
00161  */
00162 extern PRBool SEC_PKCS7VerifyDetachedSignature(SEC_PKCS7ContentInfo *cinfo,
00163                                           SECCertUsage certusage,
00164                                           SECItem *detached_digest,
00165                                           HASH_HashType digest_type,
00166                                           PRBool keepcerts);
00167 
00168 /*
00169  * SEC_PKCS7GetSignerCommonName, SEC_PKCS7GetSignerEmailAddress
00170  *      The passed-in contentInfo is espected to be Signed, and these
00171  *      functions return the specified portion of the full signer name.
00172  *
00173  *      Returns a pointer to allocated memory, which must be freed.
00174  *      A NULL return value is an error.
00175  */
00176 extern char *SEC_PKCS7GetSignerCommonName(SEC_PKCS7ContentInfo *cinfo);
00177 extern char *SEC_PKCS7GetSignerEmailAddress(SEC_PKCS7ContentInfo *cinfo);
00178 
00179 /*
00180  * Return the the signing time, in UTCTime format, of a PKCS7 contentInfo.
00181  */
00182 extern SECItem *SEC_PKCS7GetSigningTime(SEC_PKCS7ContentInfo *cinfo);
00183 
00184 
00185 /************************************************************************
00186  *     PKCS7 Creation and Encoding.
00187  ************************************************************************/
00188 
00189 /*
00190  * Start a PKCS7 signing context.
00191  *
00192  * "cert" is the cert that will be used to sign the data.  It will be
00193  * checked for validity.
00194  *
00195  * "certusage" describes the signing usage (e.g. certUsageEmailSigner)
00196  * XXX Maybe SECCertUsage should be split so that our caller just says
00197  * "email" and *we* add the "signing" part -- otherwise our caller
00198  * could be lying about the usage; we do not want to allow encryption
00199  * certs for signing or vice versa.
00200  *
00201  * "certdb" is the cert database to use for verifying the cert.
00202  * It can be NULL if a default database is available (like in the client).
00203  * 
00204  * "digestalg" names the digest algorithm (e.g. SEC_OID_SHA1).
00205  *
00206  * "digest" is the actual digest of the data.  It must be provided in
00207  * the case of detached data or NULL if the content will be included.
00208  *
00209  * The return value can be passed to functions which add things to
00210  * it like attributes, then eventually to SEC_PKCS7Encode() or to
00211  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
00212  * SEC_PKCS7DestroyContentInfo().
00213  *
00214  * An error results in a return value of NULL and an error set.
00215  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
00216  */
00217 extern SEC_PKCS7ContentInfo *
00218 SEC_PKCS7CreateSignedData (CERTCertificate *cert,
00219                         SECCertUsage certusage,
00220                         CERTCertDBHandle *certdb,
00221                         SECOidTag digestalg,
00222                         SECItem *digest,
00223                          SECKEYGetPasswordKey pwfn, void *pwfn_arg);
00224 
00225 /*
00226  * Create a PKCS7 certs-only container.
00227  *
00228  * "cert" is the (first) cert that will be included.
00229  *
00230  * "include_chain" specifies whether the entire chain for "cert" should
00231  * be included.
00232  *
00233  * "certdb" is the cert database to use for finding the chain.
00234  * It can be NULL in when "include_chain" is false, or when meaning
00235  * use the default database.
00236  *
00237  * More certs and chains can be added via AddCertficate and AddCertChain.
00238  *
00239  * An error results in a return value of NULL and an error set.
00240  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
00241  */
00242 extern SEC_PKCS7ContentInfo *
00243 SEC_PKCS7CreateCertsOnly (CERTCertificate *cert,
00244                        PRBool include_chain,
00245                        CERTCertDBHandle *certdb);
00246 
00247 /*
00248  * Start a PKCS7 enveloping context.
00249  *
00250  * "cert" is the cert for the recipient.  It will be checked for validity.
00251  *
00252  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
00253  * XXX Maybe SECCertUsage should be split so that our caller just says
00254  * "email" and *we* add the "recipient" part -- otherwise our caller
00255  * could be lying about the usage; we do not want to allow encryption
00256  * certs for signing or vice versa.
00257  *
00258  * "certdb" is the cert database to use for verifying the cert.
00259  * It can be NULL if a default database is available (like in the client).
00260  *
00261  * "encalg" specifies the bulk encryption algorithm to use (e.g. SEC_OID_RC2).
00262  *
00263  * "keysize" specifies the bulk encryption key size, in bits.
00264  *
00265  * The return value can be passed to functions which add things to
00266  * it like more recipients, then eventually to SEC_PKCS7Encode() or to
00267  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
00268  * SEC_PKCS7DestroyContentInfo().
00269  *
00270  * An error results in a return value of NULL and an error set.
00271  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
00272  */
00273 extern SEC_PKCS7ContentInfo *
00274 SEC_PKCS7CreateEnvelopedData (CERTCertificate *cert,
00275                            SECCertUsage certusage,
00276                            CERTCertDBHandle *certdb,
00277                            SECOidTag encalg,
00278                            int keysize,
00279                             SECKEYGetPasswordKey pwfn, void *pwfn_arg);
00280 
00281 /*
00282  * XXX There will be a similar routine for creating signedAndEnvelopedData.
00283  * But its parameters will be different and I have no plans to implement
00284  * it any time soon because we have no current need for it.
00285  */
00286 
00287 /*
00288  * Create an empty PKCS7 data content info.
00289  *
00290  * An error results in a return value of NULL and an error set.
00291  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
00292  */
00293 extern SEC_PKCS7ContentInfo *SEC_PKCS7CreateData (void);
00294 
00295 /*
00296  * Create an empty PKCS7 encrypted content info.
00297  *
00298  * "algorithm" specifies the bulk encryption algorithm to use.
00299  * 
00300  * An error results in a return value of NULL and an error set.
00301  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
00302  */
00303 extern SEC_PKCS7ContentInfo *
00304 SEC_PKCS7CreateEncryptedData (SECOidTag algorithm, int keysize,
00305                            SECKEYGetPasswordKey pwfn, void *pwfn_arg);
00306 
00307 /*
00308  * All of the following things return SECStatus to signal success or failure.
00309  * Failure should have a more specific error status available via
00310  * PORT_GetError()/XP_GetError().
00311  */
00312 
00313 /*
00314  * Add the specified attribute to the authenticated (i.e. signed) attributes
00315  * of "cinfo" -- "oidtag" describes the attribute and "value" is the
00316  * value to be associated with it.  NOTE! "value" must already be encoded;
00317  * no interpretation of "oidtag" is done.  Also, it is assumed that this
00318  * signedData has only one signer -- if we ever need to add attributes
00319  * when there is more than one signature, we need a way to specify *which*
00320  * signature should get the attribute.
00321  *
00322  * XXX Technically, a signed attribute can have multiple values; if/when
00323  * we ever need to support an attribute which takes multiple values, we
00324  * either need to change this interface or create an AddSignedAttributeValue
00325  * which can be called subsequently, and would then append a value.
00326  *
00327  * "cinfo" should be of type signedData (the only kind of pkcs7 data
00328  * that is allowed authenticated attributes); SECFailure will be returned
00329  * if it is not.
00330  */
00331 extern SECStatus SEC_PKCS7AddSignedAttribute (SEC_PKCS7ContentInfo *cinfo,
00332                                          SECOidTag oidtag,
00333                                          SECItem *value);
00334 
00335 /*
00336  * Add "cert" and its entire chain to the set of certs included in "cinfo".
00337  *
00338  * "certdb" is the cert database to use for finding the chain.
00339  * It can be NULL, meaning use the default database.
00340  *
00341  * "cinfo" should be of type signedData or signedAndEnvelopedData;
00342  * SECFailure will be returned if it is not.
00343  */
00344 extern SECStatus SEC_PKCS7AddCertChain (SEC_PKCS7ContentInfo *cinfo,
00345                                    CERTCertificate *cert,
00346                                    CERTCertDBHandle *certdb);
00347 
00348 /*
00349  * Add "cert" to the set of certs included in "cinfo".
00350  *
00351  * "cinfo" should be of type signedData or signedAndEnvelopedData;
00352  * SECFailure will be returned if it is not.
00353  */
00354 extern SECStatus SEC_PKCS7AddCertificate (SEC_PKCS7ContentInfo *cinfo,
00355                                      CERTCertificate *cert);
00356 
00357 /*
00358  * Add another recipient to an encrypted message.
00359  *
00360  * "cinfo" should be of type envelopedData or signedAndEnvelopedData;
00361  * SECFailure will be returned if it is not.
00362  *
00363  * "cert" is the cert for the recipient.  It will be checked for validity.
00364  *
00365  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
00366  * XXX Maybe SECCertUsage should be split so that our caller just says
00367  * "email" and *we* add the "recipient" part -- otherwise our caller
00368  * could be lying about the usage; we do not want to allow encryption
00369  * certs for signing or vice versa.
00370  *
00371  * "certdb" is the cert database to use for verifying the cert.
00372  * It can be NULL if a default database is available (like in the client).
00373  */
00374 extern SECStatus SEC_PKCS7AddRecipient (SEC_PKCS7ContentInfo *cinfo,
00375                                    CERTCertificate *cert,
00376                                    SECCertUsage certusage,
00377                                    CERTCertDBHandle *certdb);
00378 
00379 /*
00380  * Add the signing time to the authenticated (i.e. signed) attributes
00381  * of "cinfo".  This is expected to be included in outgoing signed
00382  * messages for email (S/MIME) but is likely useful in other situations.
00383  *
00384  * This should only be added once; a second call will either do
00385  * nothing or replace an old signing time with a newer one.
00386  *
00387  * XXX This will probably just shove the current time into "cinfo"
00388  * but it will not actually get signed until the entire item is
00389  * processed for encoding.  Is this (expected to be small) delay okay?
00390  *
00391  * "cinfo" should be of type signedData (the only kind of pkcs7 data
00392  * that is allowed authenticated attributes); SECFailure will be returned
00393  * if it is not.
00394  */
00395 extern SECStatus SEC_PKCS7AddSigningTime (SEC_PKCS7ContentInfo *cinfo);
00396 
00397 /*
00398  * Add the signer's symmetric capabilities to the authenticated
00399  * (i.e. signed) attributes of "cinfo".  This is expected to be
00400  * included in outgoing signed messages for email (S/MIME).
00401  *
00402  * This can only be added once; a second call will return SECFailure.
00403  *
00404  * "cinfo" should be of type signedData or signedAndEnvelopedData;
00405  * SECFailure will be returned if it is not.
00406  */
00407 extern SECStatus SEC_PKCS7AddSymmetricCapabilities(SEC_PKCS7ContentInfo *cinfo);
00408 
00409 /*
00410  * Mark that the signer's certificate and its issuing chain should
00411  * be included in the encoded data.  This is expected to be used
00412  * in outgoing signed messages for email (S/MIME).
00413  *
00414  * "certdb" is the cert database to use for finding the chain.
00415  * It can be NULL, meaning use the default database.
00416  *
00417  * "cinfo" should be of type signedData or signedAndEnvelopedData;
00418  * SECFailure will be returned if it is not.
00419  */
00420 extern SECStatus SEC_PKCS7IncludeCertChain (SEC_PKCS7ContentInfo *cinfo,
00421                                        CERTCertDBHandle *certdb);
00422 
00423 
00424 /*
00425  * Set the content; it will be included and also hashed and/or encrypted
00426  * as appropriate.  This is for in-memory content (expected to be "small")
00427  * that will be included in the PKCS7 object.  All others should stream the
00428  * content through when encoding (see SEC_PKCS7Encoder{Start,Update,Finish}).
00429  *
00430  * "buf" points to data of length "len"; it will be copied.
00431  */
00432 extern SECStatus SEC_PKCS7SetContent (SEC_PKCS7ContentInfo *cinfo,
00433                                   const char *buf, unsigned long len);
00434 
00435 /*
00436  * Encode a PKCS7 object, in one shot.  All necessary components
00437  * of the object must already be specified.  Either the data has
00438  * already been included (via SetContent), or the data is detached,
00439  * or there is no data at all (certs-only).
00440  *
00441  * "cinfo" specifies the object to be encoded.
00442  *
00443  * "outputfn" is where the encoded bytes will be passed.
00444  *
00445  * "outputarg" is an opaque argument to the above callback.
00446  *
00447  * "bulkkey" specifies the bulk encryption key to use.   This argument
00448  * can be NULL if no encryption is being done, or if the bulk key should
00449  * be generated internally (usually the case for EnvelopedData but never
00450  * for EncryptedData, which *must* provide a bulk encryption key).
00451  *
00452  * "pwfn" is a callback for getting the password which protects the
00453  * private key of the signer.  This argument can be NULL if it is known
00454  * that no signing is going to be done.
00455  *
00456  * "pwfnarg" is an opaque argument to the above callback.
00457  */
00458 extern SECStatus SEC_PKCS7Encode (SEC_PKCS7ContentInfo *cinfo,
00459                               SEC_PKCS7EncoderOutputCallback outputfn,
00460                               void *outputarg,
00461                               PK11SymKey *bulkkey,
00462                               SECKEYGetPasswordKey pwfn,
00463                               void *pwfnarg);
00464 
00465 /*
00466  * Encode a PKCS7 object, in one shot.  All necessary components
00467  * of the object must already be specified.  Either the data has
00468  * already been included (via SetContent), or the data is detached,
00469  * or there is no data at all (certs-only).  The output, rather than
00470  * being passed to an output function as is done above, is all put
00471  * into a SECItem.
00472  *
00473  * "pool" specifies a pool from which to allocate the result.
00474  * It can be NULL, in which case memory is allocated generically.
00475  *
00476  * "dest" specifies a SECItem in which to put the result data.
00477  * It can be NULL, in which case the entire item is allocated, too.
00478  *
00479  * "cinfo" specifies the object to be encoded.
00480  *
00481  * "bulkkey" specifies the bulk encryption key to use.   This argument
00482  * can be NULL if no encryption is being done, or if the bulk key should
00483  * be generated internally (usually the case for EnvelopedData but never
00484  * for EncryptedData, which *must* provide a bulk encryption key).
00485  *
00486  * "pwfn" is a callback for getting the password which protects the
00487  * private key of the signer.  This argument can be NULL if it is known
00488  * that no signing is going to be done.
00489  *
00490  * "pwfnarg" is an opaque argument to the above callback.
00491  */
00492 extern SECItem *SEC_PKCS7EncodeItem (PRArenaPool *pool,
00493                                  SECItem *dest,
00494                                  SEC_PKCS7ContentInfo *cinfo,
00495                                  PK11SymKey *bulkkey,
00496                                  SECKEYGetPasswordKey pwfn,
00497                                  void *pwfnarg);
00498 
00499 /*
00500  * For those who want to simply point to the pkcs7 contentInfo ASN.1
00501  * template, and *not* call the encoding functions directly, the
00502  * following function can be used -- after it is called, the entire
00503  * PKCS7 contentInfo is ready to be encoded.
00504  */
00505 extern SECStatus SEC_PKCS7PrepareForEncode (SEC_PKCS7ContentInfo *cinfo,
00506                                        PK11SymKey *bulkkey,
00507                                        SECKEYGetPasswordKey pwfn,
00508                                        void *pwfnarg);
00509 
00510 /*
00511  * Start the process of encoding a PKCS7 object.  The first part of
00512  * the encoded object will be passed to the output function right away;
00513  * after that it is expected that SEC_PKCS7EncoderUpdate will be called,
00514  * streaming in the actual content that is getting included as well as
00515  * signed or encrypted (or both).
00516  *
00517  * "cinfo" specifies the object to be encoded.
00518  *
00519  * "outputfn" is where the encoded bytes will be passed.
00520  *
00521  * "outputarg" is an opaque argument to the above callback.
00522  *
00523  * "bulkkey" specifies the bulk encryption key to use.   This argument
00524  * can be NULL if no encryption is being done, or if the bulk key should
00525  * be generated internally (usually the case for EnvelopedData but never
00526  * for EncryptedData, which *must* provide a bulk encryption key).
00527  *
00528  * Returns an object to be passed to EncoderUpdate and EncoderFinish.
00529  */
00530 extern SEC_PKCS7EncoderContext *
00531 SEC_PKCS7EncoderStart (SEC_PKCS7ContentInfo *cinfo,
00532                      SEC_PKCS7EncoderOutputCallback outputfn,
00533                      void *outputarg,
00534                      PK11SymKey *bulkkey);
00535 
00536 /*
00537  * Encode more contents, hashing and/or encrypting along the way.
00538  */
00539 extern SECStatus SEC_PKCS7EncoderUpdate (SEC_PKCS7EncoderContext *p7ecx,
00540                                     const char *buf,
00541                                     unsigned long len);
00542 
00543 /*
00544  * No more contents; finish the signature creation, if appropriate,
00545  * and then the encoding.
00546  *
00547  * "pwfn" is a callback for getting the password which protects the
00548  * signer's private key.  This argument can be NULL if it is known
00549  * that no signing is going to be done.
00550  *
00551  * "pwfnarg" is an opaque argument to the above callback.
00552  */
00553 extern SECStatus SEC_PKCS7EncoderFinish (SEC_PKCS7EncoderContext *p7ecx,
00554                                     SECKEYGetPasswordKey pwfn,
00555                                     void *pwfnarg);
00556 
00557 /*  Abort the underlying ASN.1 stream & set an error  */
00558 void SEC_PKCS7EncoderAbort(SEC_PKCS7EncoderContext *p7dcx, int error);
00559 
00560 /* retrieve the algorithm ID used to encrypt the content info
00561  * for encrypted and enveloped data.  The SECAlgorithmID pointer
00562  * returned needs to be freed as it is a copy of the algorithm
00563  * id in the content info.
00564  */ 
00565 extern SECAlgorithmID *
00566 SEC_PKCS7GetEncryptionAlgorithm(SEC_PKCS7ContentInfo *cinfo); 
00567 
00568 /* the content of an encrypted data content info is encrypted.
00569  * it is assumed that for encrypted data, that the data has already
00570  * been set and is in the "plainContent" field of the content info.
00571  *
00572  * cinfo is the content info to encrypt
00573  *
00574  * key is the key with which to perform the encryption.  if the
00575  *     algorithm is a password based encryption algorithm, the
00576  *     key is actually a password which will be processed per
00577  *     PKCS #5.
00578  * 
00579  * in the event of an error, SECFailure is returned.  SECSuccess
00580  * indicates a success.
00581  */
00582 extern SECStatus 
00583 SEC_PKCS7EncryptContents(PRArenaPool *poolp,
00584                       SEC_PKCS7ContentInfo *cinfo, 
00585                       SECItem *key,
00586                       void *wincx); 
00587        
00588 /* the content of an encrypted data content info is decrypted.
00589  * it is assumed that for encrypted data, that the data has already
00590  * been set and is in the "encContent" field of the content info.
00591  *
00592  * cinfo is the content info to decrypt
00593  *
00594  * key is the key with which to perform the decryption.  if the
00595  *     algorithm is a password based encryption algorithm, the
00596  *     key is actually a password which will be processed per
00597  *     PKCS #5.
00598  * 
00599  * in the event of an error, SECFailure is returned.  SECSuccess
00600  * indicates a success.
00601  */
00602 extern SECStatus 
00603 SEC_PKCS7DecryptContents(PRArenaPool *poolp,
00604                       SEC_PKCS7ContentInfo *cinfo, 
00605                       SECItem *key,
00606                       void *wincx); 
00607 
00608 /* retrieve the certificate list from the content info.  the list
00609  * is a pointer to the list in the content info.  this should not
00610  * be deleted or freed in any way short of calling 
00611  * SEC_PKCS7DestroyContentInfo
00612  */
00613 extern SECItem **
00614 SEC_PKCS7GetCertificateList(SEC_PKCS7ContentInfo *cinfo);
00615 
00616 /* Returns the key length (in bits) of the algorithm used to encrypt
00617    this object.  Returns 0 if it's not encrypted, or the key length is
00618    irrelevant. */
00619 extern int 
00620 SEC_PKCS7GetKeyLength(SEC_PKCS7ContentInfo *cinfo);
00621  
00622 
00623 /************************************************************************/
00624 SEC_END_PROTOS
00625 
00626 #endif /* _SECPKCS7_H_ */