security/nss/lib/pkcs7/secpkcs7.h

   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  * Interface to the PKCS7 implementation.
  39  *
  40  * $Id: secpkcs7.h,v 1.6 2008/06/14 14:20:25 wtc%google.com Exp $
  41  */
  42
  43 #ifndef _SECPKCS7_H_
  44 #define _SECPKCS7_H_
  45
  46 #include "seccomon.h"
  47
  48 #include "secoidt.h"
  49 #include "certt.h"
  50 #include "keyt.h"
  51 #include "hasht.h"
  52 #include "pkcs7t.h"
  53
  54 extern const SEC_ASN1Template sec_PKCS7ContentInfoTemplate[];
  55
  56 /************************************************************************/
  57 SEC_BEGIN_PROTOS
  58
  59 /************************************************************************
  60  *      Miscellaneous
  61  ************************************************************************/
  62
  63 /*
  64  * Returns the content type of the given contentInfo.
  65  */
  66 extern SECOidTag SEC_PKCS7ContentType (SEC_PKCS7ContentInfo *cinfo);
  67
  68 /*
  69  * Destroy a PKCS7 contentInfo and all of its sub-pieces.
  70  */
  71 extern void SEC_PKCS7DestroyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
  72
  73 /*
  74  * Copy a PKCS7 contentInfo.  A Destroy is needed on *each* copy.
  75  */
  76 extern SEC_PKCS7ContentInfo *
  77 SEC_PKCS7CopyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
  78
  79 /*
  80  * Return a pointer to the actual content.  In the case of those types
  81  * which are encrypted, this returns the *plain* content.
  82  */
  83 extern SECItem *SEC_PKCS7GetContent(SEC_PKCS7ContentInfo *cinfo);
  84
  85 /************************************************************************
  86  *      PKCS7 Decoding, Verification, etc..
  87  ************************************************************************/
  88
  89 extern SEC_PKCS7DecoderContext *
  90 SEC_PKCS7DecoderStart(SEC_PKCS7DecoderContentCallback callback,
  91                       void *callback_arg,
  92                       SECKEYGetPasswordKey pwfn, void *pwfn_arg,
  93                       SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb,
  94                       void *decrypt_key_cb_arg,
  95                       SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
  96
  97 extern SECStatus
  98 SEC_PKCS7DecoderUpdate(SEC_PKCS7DecoderContext *p7dcx,
  99                        const char *buf, unsigned long len);
 100
 101 extern SEC_PKCS7ContentInfo *
 102 SEC_PKCS7DecoderFinish(SEC_PKCS7DecoderContext *p7dcx);
 103
 104
 105 /*  Abort the underlying ASN.1 stream & set an error  */
 106 void SEC_PKCS7DecoderAbort(SEC_PKCS7DecoderContext *p7dcx, int error);
 107
 108 extern SEC_PKCS7ContentInfo *
 109 SEC_PKCS7DecodeItem(SECItem *p7item,
 110                     SEC_PKCS7DecoderContentCallback cb, void *cb_arg,
 111                     SECKEYGetPasswordKey pwfn, void *pwfn_arg,
 112                     SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb,
 113                     void *decrypt_key_cb_arg,
 114                     SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
 115
 116 extern PRBool SEC_PKCS7ContainsCertsOrCrls(SEC_PKCS7ContentInfo *cinfo);
 117
 118 /* checks to see if the contents of the content info is
 119  * empty.  it so, PR_TRUE is returned.  PR_FALSE, otherwise.
 120  *
 121  * minLen is used to specify a minimum size.  if content size <= minLen,
 122  * content is assumed empty.
 123  */
 124 extern PRBool
 125 SEC_PKCS7IsContentEmpty(SEC_PKCS7ContentInfo *cinfo, unsigned int minLen);
 126
 127 extern PRBool SEC_PKCS7ContentIsEncrypted(SEC_PKCS7ContentInfo *cinfo);
 128
 129 /*
 130  * If the PKCS7 content has a signature (not just *could* have a signature)
 131  * return true; false otherwise.  This can/should be called before calling
 132  * VerifySignature, which will always indicate failure if no signature is
 133  * present, but that does not mean there even was a signature!
 134  * Note that the content itself can be empty (detached content was sent
 135  * another way); it is the presence of the signature that matters.
 136  */
 137 extern PRBool SEC_PKCS7ContentIsSigned(SEC_PKCS7ContentInfo *cinfo);
 138
 139 /*
 140  * SEC_PKCS7VerifySignature
 141  *      Look at a PKCS7 contentInfo and check if the signature is good.
 142  *      The verification checks that the signing cert is valid and trusted
 143  *      for the purpose specified by "certusage".
 144  *
 145  *      In addition, if "keepcerts" is true, add any new certificates found
 146  *      into our local database.
 147  */
 148 extern PRBool SEC_PKCS7VerifySignature(SEC_PKCS7ContentInfo *cinfo,
 149                                        SECCertUsage certusage,
 150                                        PRBool keepcerts);
 151
 152 /*
 153  * SEC_PKCS7VerifyDetachedSignature
 154  *      Look at a PKCS7 contentInfo and check if the signature matches
 155  *      a passed-in digest (calculated, supposedly, from detached contents).
 156  *      The verification checks that the signing cert is valid and trusted
 157  *      for the purpose specified by "certusage".
 158  *
 159  *      In addition, if "keepcerts" is true, add any new certificates found
 160  *      into our local database.
 161  */
 162 extern PRBool SEC_PKCS7VerifyDetachedSignature(SEC_PKCS7ContentInfo *cinfo,
 163                                                SECCertUsage certusage,
 164                                                SECItem *detached_digest,
 165                                                HASH_HashType digest_type,
 166                                                PRBool keepcerts);
 167
 168 /*
 169  * SEC_PKCS7GetSignerCommonName, SEC_PKCS7GetSignerEmailAddress
 170  *      The passed-in contentInfo is espected to be Signed, and these
 171  *      functions return the specified portion of the full signer name.
 172  *
 173  *      Returns a pointer to allocated memory, which must be freed.
 174  *      A NULL return value is an error.
 175  */
 176 extern char *SEC_PKCS7GetSignerCommonName(SEC_PKCS7ContentInfo *cinfo);
 177 extern char *SEC_PKCS7GetSignerEmailAddress(SEC_PKCS7ContentInfo *cinfo);
 178
 179 /*
 180  * Return the the signing time, in UTCTime format, of a PKCS7 contentInfo.
 181  */
 182 extern SECItem *SEC_PKCS7GetSigningTime(SEC_PKCS7ContentInfo *cinfo);
 183
 184
 185 /************************************************************************
 186  *      PKCS7 Creation and Encoding.
 187  ************************************************************************/
 188
 189 /*
 190  * Start a PKCS7 signing context.
 191  *
 192  * "cert" is the cert that will be used to sign the data.  It will be
 193  * checked for validity.
 194  *
 195  * "certusage" describes the signing usage (e.g. certUsageEmailSigner)
 196  * XXX Maybe SECCertUsage should be split so that our caller just says
 197  * "email" and *we* add the "signing" part -- otherwise our caller
 198  * could be lying about the usage; we do not want to allow encryption
 199  * certs for signing or vice versa.
 200  *
 201  * "certdb" is the cert database to use for verifying the cert.
 202  * It can be NULL if a default database is available (like in the client).
 203  *
 204  * "digestalg" names the digest algorithm (e.g. SEC_OID_SHA1).
 205  *
 206  * "digest" is the actual digest of the data.  It must be provided in
 207  * the case of detached data or NULL if the content will be included.
 208  *
 209  * The return value can be passed to functions which add things to
 210  * it like attributes, then eventually to SEC_PKCS7Encode() or to
 211  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
 212  * SEC_PKCS7DestroyContentInfo().
 213  *
 214  * An error results in a return value of NULL and an error set.
 215  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
 216  */
 217 extern SEC_PKCS7ContentInfo *
 218 SEC_PKCS7CreateSignedData (CERTCertificate *cert,
 219                            SECCertUsage certusage,
 220                            CERTCertDBHandle *certdb,
 221                            SECOidTag digestalg,
 222                            SECItem *digest,
 223                            SECKEYGetPasswordKey pwfn, void *pwfn_arg);
 224
 225 /*
 226  * Create a PKCS7 certs-only container.
 227  *
 228  * "cert" is the (first) cert that will be included.
 229  *
 230  * "include_chain" specifies whether the entire chain for "cert" should
 231  * be included.
 232  *
 233  * "certdb" is the cert database to use for finding the chain.
 234  * It can be NULL in when "include_chain" is false, or when meaning
 235  * use the default database.
 236  *
 237  * More certs and chains can be added via AddCertficate and AddCertChain.
 238  *
 239  * An error results in a return value of NULL and an error set.
 240  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
 241  */
 242 extern SEC_PKCS7ContentInfo *
 243 SEC_PKCS7CreateCertsOnly (CERTCertificate *cert,
 244                           PRBool include_chain,
 245                           CERTCertDBHandle *certdb);
 246
 247 /*
 248  * Start a PKCS7 enveloping context.
 249  *
 250  * "cert" is the cert for the recipient.  It will be checked for validity.
 251  *
 252  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
 253  * XXX Maybe SECCertUsage should be split so that our caller just says
 254  * "email" and *we* add the "recipient" part -- otherwise our caller
 255  * could be lying about the usage; we do not want to allow encryption
 256  * certs for signing or vice versa.
 257  *
 258  * "certdb" is the cert database to use for verifying the cert.
 259  * It can be NULL if a default database is available (like in the client).
 260  *
 261  * "encalg" specifies the bulk encryption algorithm to use (e.g. SEC_OID_RC2).
 262  *
 263  * "keysize" specifies the bulk encryption key size, in bits.
 264  *
 265  * The return value can be passed to functions which add things to
 266  * it like more recipients, then eventually to SEC_PKCS7Encode() or to
 267  * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
 268  * SEC_PKCS7DestroyContentInfo().
 269  *
 270  * An error results in a return value of NULL and an error set.
 271  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
 272  */
 273 extern SEC_PKCS7ContentInfo *
 274 SEC_PKCS7CreateEnvelopedData (CERTCertificate *cert,
 275                               SECCertUsage certusage,
 276                               CERTCertDBHandle *certdb,
 277                               SECOidTag encalg,
 278                               int keysize,
 279                               SECKEYGetPasswordKey pwfn, void *pwfn_arg);
 280
 281 /*
 282  * XXX There will be a similar routine for creating signedAndEnvelopedData.
 283  * But its parameters will be different and I have no plans to implement
 284  * it any time soon because we have no current need for it.
 285  */
 286
 287 /*
 288  * Create an empty PKCS7 data content info.
 289  *
 290  * An error results in a return value of NULL and an error set.
 291  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
 292  */
 293 extern SEC_PKCS7ContentInfo *SEC_PKCS7CreateData (void);
 294
 295 /*
 296  * Create an empty PKCS7 encrypted content info.
 297  *
 298  * "algorithm" specifies the bulk encryption algorithm to use.
 299  *
 300  * An error results in a return value of NULL and an error set.
 301  * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
 302  */
 303 extern SEC_PKCS7ContentInfo *
 304 SEC_PKCS7CreateEncryptedData (SECOidTag algorithm, int keysize,
 305                               SECKEYGetPasswordKey pwfn, void *pwfn_arg);
 306
 307 /*
 308  * All of the following things return SECStatus to signal success or failure.
 309  * Failure should have a more specific error status available via
 310  * PORT_GetError()/XP_GetError().
 311  */
 312
 313 /*
 314  * Add the specified attribute to the authenticated (i.e. signed) attributes
 315  * of "cinfo" -- "oidtag" describes the attribute and "value" is the
 316  * value to be associated with it.  NOTE! "value" must already be encoded;
 317  * no interpretation of "oidtag" is done.  Also, it is assumed that this
 318  * signedData has only one signer -- if we ever need to add attributes
 319  * when there is more than one signature, we need a way to specify *which*
 320  * signature should get the attribute.
 321  *
 322  * XXX Technically, a signed attribute can have multiple values; if/when
 323  * we ever need to support an attribute which takes multiple values, we
 324  * either need to change this interface or create an AddSignedAttributeValue
 325  * which can be called subsequently, and would then append a value.
 326  *
 327  * "cinfo" should be of type signedData (the only kind of pkcs7 data
 328  * that is allowed authenticated attributes); SECFailure will be returned
 329  * if it is not.
 330  */
 331 extern SECStatus SEC_PKCS7AddSignedAttribute (SEC_PKCS7ContentInfo *cinfo,
 332                                               SECOidTag oidtag,
 333                                               SECItem *value);
 334
 335 /*
 336  * Add "cert" and its entire chain to the set of certs included in "cinfo".
 337  *
 338  * "certdb" is the cert database to use for finding the chain.
 339  * It can be NULL, meaning use the default database.
 340  *
 341  * "cinfo" should be of type signedData or signedAndEnvelopedData;
 342  * SECFailure will be returned if it is not.
 343  */
 344 extern SECStatus SEC_PKCS7AddCertChain (SEC_PKCS7ContentInfo *cinfo,
 345                                         CERTCertificate *cert,
 346                                         CERTCertDBHandle *certdb);
 347
 348 /*
 349  * Add "cert" to the set of certs included in "cinfo".
 350  *
 351  * "cinfo" should be of type signedData or signedAndEnvelopedData;
 352  * SECFailure will be returned if it is not.
 353  */
 354 extern SECStatus SEC_PKCS7AddCertificate (SEC_PKCS7ContentInfo *cinfo,
 355                                           CERTCertificate *cert);
 356
 357 /*
 358  * Add another recipient to an encrypted message.
 359  *
 360  * "cinfo" should be of type envelopedData or signedAndEnvelopedData;
 361  * SECFailure will be returned if it is not.
 362  *
 363  * "cert" is the cert for the recipient.  It will be checked for validity.
 364  *
 365  * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
 366  * XXX Maybe SECCertUsage should be split so that our caller just says
 367  * "email" and *we* add the "recipient" part -- otherwise our caller
 368  * could be lying about the usage; we do not want to allow encryption
 369  * certs for signing or vice versa.
 370  *
 371  * "certdb" is the cert database to use for verifying the cert.
 372  * It can be NULL if a default database is available (like in the client).
 373  */
 374 extern SECStatus SEC_PKCS7AddRecipient (SEC_PKCS7ContentInfo *cinfo,
 375                                         CERTCertificate *cert,
 376                                         SECCertUsage certusage,
 377                                         CERTCertDBHandle *certdb);
 378
 379 /*
 380  * Add the signing time to the authenticated (i.e. signed) attributes
 381  * of "cinfo".  This is expected to be included in outgoing signed
 382  * messages for email (S/MIME) but is likely useful in other situations.
 383  *
 384  * This should only be added once; a second call will either do
 385  * nothing or replace an old signing time with a newer one.
 386  *
 387  * XXX This will probably just shove the current time into "cinfo"
 388  * but it will not actually get signed until the entire item is
 389  * processed for encoding.  Is this (expected to be small) delay okay?
 390  *
 391  * "cinfo" should be of type signedData (the only kind of pkcs7 data
 392  * that is allowed authenticated attributes); SECFailure will be returned
 393  * if it is not.
 394  */
 395 extern SECStatus SEC_PKCS7AddSigningTime (SEC_PKCS7ContentInfo *cinfo);
 396
 397 /*
 398  * Add the signer's symmetric capabilities to the authenticated
 399  * (i.e. signed) attributes of "cinfo".  This is expected to be
 400  * included in outgoing signed messages for email (S/MIME).
 401  *
 402  * This can only be added once; a second call will return SECFailure.
 403  *
 404  * "cinfo" should be of type signedData or signedAndEnvelopedData;
 405  * SECFailure will be returned if it is not.
 406  */
 407 extern SECStatus SEC_PKCS7AddSymmetricCapabilities(SEC_PKCS7ContentInfo *cinfo);
 408
 409 /*
 410  * Mark that the signer's certificate and its issuing chain should
 411  * be included in the encoded data.  This is expected to be used
 412  * in outgoing signed messages for email (S/MIME).
 413  *
 414  * "certdb" is the cert database to use for finding the chain.
 415  * It can be NULL, meaning use the default database.
 416  *
 417  * "cinfo" should be of type signedData or signedAndEnvelopedData;
 418  * SECFailure will be returned if it is not.
 419  */
 420 extern SECStatus SEC_PKCS7IncludeCertChain (SEC_PKCS7ContentInfo *cinfo,
 421                                             CERTCertDBHandle *certdb);
 422
 423
 424 /*
 425  * Set the content; it will be included and also hashed and/or encrypted
 426  * as appropriate.  This is for in-memory content (expected to be "small")
 427  * that will be included in the PKCS7 object.  All others should stream the
 428  * content through when encoding (see SEC_PKCS7Encoder{Start,Update,Finish}).
 429  *
 430  * "buf" points to data of length "len"; it will be copied.
 431  */
 432 extern SECStatus SEC_PKCS7SetContent (SEC_PKCS7ContentInfo *cinfo,
 433                                       const char *buf, unsigned long len);
 434
 435 /*
 436  * Encode a PKCS7 object, in one shot.  All necessary components
 437  * of the object must already be specified.  Either the data has
 438  * already been included (via SetContent), or the data is detached,
 439  * or there is no data at all (certs-only).
 440  *
 441  * "cinfo" specifies the object to be encoded.
 442  *
 443  * "outputfn" is where the encoded bytes will be passed.
 444  *
 445  * "outputarg" is an opaque argument to the above callback.
 446  *
 447  * "bulkkey" specifies the bulk encryption key to use.   This argument
 448  * can be NULL if no encryption is being done, or if the bulk key should
 449  * be generated internally (usually the case for EnvelopedData but never
 450  * for EncryptedData, which *must* provide a bulk encryption key).
 451  *
 452  * "pwfn" is a callback for getting the password which protects the
 453  * private key of the signer.  This argument can be NULL if it is known
 454  * that no signing is going to be done.
 455  *
 456  * "pwfnarg" is an opaque argument to the above callback.
 457  */
 458 extern SECStatus SEC_PKCS7Encode (SEC_PKCS7ContentInfo *cinfo,
 459                                   SEC_PKCS7EncoderOutputCallback outputfn,
 460                                   void *outputarg,
 461                                   PK11SymKey *bulkkey,
 462                                   SECKEYGetPasswordKey pwfn,
 463                                   void *pwfnarg);
 464
 465 /*
 466  * Encode a PKCS7 object, in one shot.  All necessary components
 467  * of the object must already be specified.  Either the data has
 468  * already been included (via SetContent), or the data is detached,
 469  * or there is no data at all (certs-only).  The output, rather than
 470  * being passed to an output function as is done above, is all put
 471  * into a SECItem.
 472  *
 473  * "pool" specifies a pool from which to allocate the result.
 474  * It can be NULL, in which case memory is allocated generically.
 475  *
 476  * "dest" specifies a SECItem in which to put the result data.
 477  * It can be NULL, in which case the entire item is allocated, too.
 478  *
 479  * "cinfo" specifies the object to be encoded.
 480  *
 481  * "bulkkey" specifies the bulk encryption key to use.   This argument
 482  * can be NULL if no encryption is being done, or if the bulk key should
 483  * be generated internally (usually the case for EnvelopedData but never
 484  * for EncryptedData, which *must* provide a bulk encryption key).
 485  *
 486  * "pwfn" is a callback for getting the password which protects the
 487  * private key of the signer.  This argument can be NULL if it is known
 488  * that no signing is going to be done.
 489  *
 490  * "pwfnarg" is an opaque argument to the above callback.
 491  */
 492 extern SECItem *SEC_PKCS7EncodeItem (PLArenaPool *pool,
 493                                      SECItem *dest,
 494                                      SEC_PKCS7ContentInfo *cinfo,
 495                                      PK11SymKey *bulkkey,
 496                                      SECKEYGetPasswordKey pwfn,
 497                                      void *pwfnarg);
 498
 499 /*
 500  * For those who want to simply point to the pkcs7 contentInfo ASN.1
 501  * template, and *not* call the encoding functions directly, the
 502  * following function can be used -- after it is called, the entire
 503  * PKCS7 contentInfo is ready to be encoded.
 504  */
 505 extern SECStatus SEC_PKCS7PrepareForEncode (SEC_PKCS7ContentInfo *cinfo,
 506                                             PK11SymKey *bulkkey,
 507                                             SECKEYGetPasswordKey pwfn,
 508                                             void *pwfnarg);
 509
 510 /*
 511  * Start the process of encoding a PKCS7 object.  The first part of
 512  * the encoded object will be passed to the output function right away;
 513  * after that it is expected that SEC_PKCS7EncoderUpdate will be called,
 514  * streaming in the actual content that is getting included as well as
 515  * signed or encrypted (or both).
 516  *
 517  * "cinfo" specifies the object to be encoded.
 518  *
 519  * "outputfn" is where the encoded bytes will be passed.
 520  *
 521  * "outputarg" is an opaque argument to the above callback.
 522  *
 523  * "bulkkey" specifies the bulk encryption key to use.   This argument
 524  * can be NULL if no encryption is being done, or if the bulk key should
 525  * be generated internally (usually the case for EnvelopedData but never
 526  * for EncryptedData, which *must* provide a bulk encryption key).
 527  *
 528  * Returns an object to be passed to EncoderUpdate and EncoderFinish.
 529  */
 530 extern SEC_PKCS7EncoderContext *
 531 SEC_PKCS7EncoderStart (SEC_PKCS7ContentInfo *cinfo,
 532                        SEC_PKCS7EncoderOutputCallback outputfn,
 533                        void *outputarg,
 534                        PK11SymKey *bulkkey);
 535
 536 /*
 537  * Encode more contents, hashing and/or encrypting along the way.
 538  */
 539 extern SECStatus SEC_PKCS7EncoderUpdate (SEC_PKCS7EncoderContext *p7ecx,
 540                                          const char *buf,
 541                                          unsigned long len);
 542
 543 /*
 544  * No more contents; finish the signature creation, if appropriate,
 545  * and then the encoding.
 546  *
 547  * "pwfn" is a callback for getting the password which protects the
 548  * signer's private key.  This argument can be NULL if it is known
 549  * that no signing is going to be done.
 550  *
 551  * "pwfnarg" is an opaque argument to the above callback.
 552  */
 553 extern SECStatus SEC_PKCS7EncoderFinish (SEC_PKCS7EncoderContext *p7ecx,
 554                                          SECKEYGetPasswordKey pwfn,
 555                                          void *pwfnarg);
 556
 557 /*  Abort the underlying ASN.1 stream & set an error  */
 558 void SEC_PKCS7EncoderAbort(SEC_PKCS7EncoderContext *p7dcx, int error);
 559
 560 /* retrieve the algorithm ID used to encrypt the content info
 561  * for encrypted and enveloped data.  The SECAlgorithmID pointer
 562  * returned needs to be freed as it is a copy of the algorithm
 563  * id in the content info.
 564  */
 565 extern SECAlgorithmID *
 566 SEC_PKCS7GetEncryptionAlgorithm(SEC_PKCS7ContentInfo *cinfo);
 567
 568 /* the content of an encrypted data content info is encrypted.
 569  * it is assumed that for encrypted data, that the data has already
 570  * been set and is in the "plainContent" field of the content info.
 571  *
 572  * cinfo is the content info to encrypt
 573  *
 574  * key is the key with which to perform the encryption.  if the
 575  *     algorithm is a password based encryption algorithm, the
 576  *     key is actually a password which will be processed per
 577  *     PKCS #5.
 578  *
 579  * in the event of an error, SECFailure is returned.  SECSuccess
 580  * indicates a success.
 581  */
 582 extern SECStatus
 583 SEC_PKCS7EncryptContents(PLArenaPool *poolp,
 584                          SEC_PKCS7ContentInfo *cinfo,
 585                          SECItem *key,
 586                          void *wincx);
 587
 588 /* the content of an encrypted data content info is decrypted.
 589  * it is assumed that for encrypted data, that the data has already
 590  * been set and is in the "encContent" field of the content info.
 591  *
 592  * cinfo is the content info to decrypt
 593  *
 594  * key is the key with which to perform the decryption.  if the
 595  *     algorithm is a password based encryption algorithm, the
 596  *     key is actually a password which will be processed per
 597  *     PKCS #5.
 598  *
 599  * in the event of an error, SECFailure is returned.  SECSuccess
 600  * indicates a success.
 601  */
 602 extern SECStatus
 603 SEC_PKCS7DecryptContents(PLArenaPool *poolp,
 604                          SEC_PKCS7ContentInfo *cinfo,
 605                          SECItem *key,
 606                          void *wincx);
 607
 608 /* retrieve the certificate list from the content info.  the list
 609  * is a pointer to the list in the content info.  this should not
 610  * be deleted or freed in any way short of calling
 611  * SEC_PKCS7DestroyContentInfo
 612  */
 613 extern SECItem **
 614 SEC_PKCS7GetCertificateList(SEC_PKCS7ContentInfo *cinfo);
 615
 616 /* Returns the key length (in bits) of the algorithm used to encrypt
 617    this object.  Returns 0 if it's not encrypted, or the key length is
 618    irrelevant. */
 619 extern int
 620 SEC_PKCS7GetKeyLength(SEC_PKCS7ContentInfo *cinfo);
 621
 622
 623 /************************************************************************/
 624 SEC_END_PROTOS
 625
 626 #endif /* _SECPKCS7_H_ */