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

source code of include/nss/secpkcs7.h