1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/pkcs7/secpkcs7.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,610 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 + * Interface to the PKCS7 implementation.
1.10 + */
1.11 +
1.12 +#ifndef _SECPKCS7_H_
1.13 +#define _SECPKCS7_H_
1.14 +
1.15 +#include "seccomon.h"
1.16 +
1.17 +#include "secoidt.h"
1.18 +#include "certt.h"
1.19 +#include "keyt.h"
1.20 +#include "hasht.h"
1.21 +#include "pkcs7t.h"
1.22 +
1.23 +extern const SEC_ASN1Template sec_PKCS7ContentInfoTemplate[];
1.24 +
1.25 +/************************************************************************/
1.26 +SEC_BEGIN_PROTOS
1.27 +
1.28 +/************************************************************************
1.29 + * Miscellaneous
1.30 + ************************************************************************/
1.31 +
1.32 +/*
1.33 + * Returns the content type of the given contentInfo.
1.34 + */
1.35 +extern SECOidTag SEC_PKCS7ContentType (SEC_PKCS7ContentInfo *cinfo);
1.36 +
1.37 +/*
1.38 + * Destroy a PKCS7 contentInfo and all of its sub-pieces.
1.39 + */
1.40 +extern void SEC_PKCS7DestroyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
1.41 +
1.42 +/*
1.43 + * Copy a PKCS7 contentInfo. A Destroy is needed on *each* copy.
1.44 + */
1.45 +extern SEC_PKCS7ContentInfo *
1.46 +SEC_PKCS7CopyContentInfo(SEC_PKCS7ContentInfo *contentInfo);
1.47 +
1.48 +/*
1.49 + * Return a pointer to the actual content. In the case of those types
1.50 + * which are encrypted, this returns the *plain* content.
1.51 + */
1.52 +extern SECItem *SEC_PKCS7GetContent(SEC_PKCS7ContentInfo *cinfo);
1.53 +
1.54 +/************************************************************************
1.55 + * PKCS7 Decoding, Verification, etc..
1.56 + ************************************************************************/
1.57 +
1.58 +extern SEC_PKCS7DecoderContext *
1.59 +SEC_PKCS7DecoderStart(SEC_PKCS7DecoderContentCallback callback,
1.60 + void *callback_arg,
1.61 + SECKEYGetPasswordKey pwfn, void *pwfn_arg,
1.62 + SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb,
1.63 + void *decrypt_key_cb_arg,
1.64 + SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
1.65 +
1.66 +extern SECStatus
1.67 +SEC_PKCS7DecoderUpdate(SEC_PKCS7DecoderContext *p7dcx,
1.68 + const char *buf, unsigned long len);
1.69 +
1.70 +extern SEC_PKCS7ContentInfo *
1.71 +SEC_PKCS7DecoderFinish(SEC_PKCS7DecoderContext *p7dcx);
1.72 +
1.73 +
1.74 +/* Abort the underlying ASN.1 stream & set an error */
1.75 +void SEC_PKCS7DecoderAbort(SEC_PKCS7DecoderContext *p7dcx, int error);
1.76 +
1.77 +extern SEC_PKCS7ContentInfo *
1.78 +SEC_PKCS7DecodeItem(SECItem *p7item,
1.79 + SEC_PKCS7DecoderContentCallback cb, void *cb_arg,
1.80 + SECKEYGetPasswordKey pwfn, void *pwfn_arg,
1.81 + SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb,
1.82 + void *decrypt_key_cb_arg,
1.83 + SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb);
1.84 +
1.85 +extern PRBool SEC_PKCS7ContainsCertsOrCrls(SEC_PKCS7ContentInfo *cinfo);
1.86 +
1.87 +/* checks to see if the contents of the content info is
1.88 + * empty. it so, PR_TRUE is returned. PR_FALSE, otherwise.
1.89 + *
1.90 + * minLen is used to specify a minimum size. if content size <= minLen,
1.91 + * content is assumed empty.
1.92 + */
1.93 +extern PRBool
1.94 +SEC_PKCS7IsContentEmpty(SEC_PKCS7ContentInfo *cinfo, unsigned int minLen);
1.95 +
1.96 +extern PRBool SEC_PKCS7ContentIsEncrypted(SEC_PKCS7ContentInfo *cinfo);
1.97 +
1.98 +/*
1.99 + * If the PKCS7 content has a signature (not just *could* have a signature)
1.100 + * return true; false otherwise. This can/should be called before calling
1.101 + * VerifySignature, which will always indicate failure if no signature is
1.102 + * present, but that does not mean there even was a signature!
1.103 + * Note that the content itself can be empty (detached content was sent
1.104 + * another way); it is the presence of the signature that matters.
1.105 + */
1.106 +extern PRBool SEC_PKCS7ContentIsSigned(SEC_PKCS7ContentInfo *cinfo);
1.107 +
1.108 +/*
1.109 + * SEC_PKCS7VerifySignature
1.110 + * Look at a PKCS7 contentInfo and check if the signature is good.
1.111 + * The verification checks that the signing cert is valid and trusted
1.112 + * for the purpose specified by "certusage".
1.113 + *
1.114 + * In addition, if "keepcerts" is true, add any new certificates found
1.115 + * into our local database.
1.116 + */
1.117 +extern PRBool SEC_PKCS7VerifySignature(SEC_PKCS7ContentInfo *cinfo,
1.118 + SECCertUsage certusage,
1.119 + PRBool keepcerts);
1.120 +
1.121 +/*
1.122 + * SEC_PKCS7VerifyDetachedSignature
1.123 + * Look at a PKCS7 contentInfo and check if the signature matches
1.124 + * a passed-in digest (calculated, supposedly, from detached contents).
1.125 + * The verification checks that the signing cert is valid and trusted
1.126 + * for the purpose specified by "certusage".
1.127 + *
1.128 + * In addition, if "keepcerts" is true, add any new certificates found
1.129 + * into our local database.
1.130 + */
1.131 +extern PRBool SEC_PKCS7VerifyDetachedSignature(SEC_PKCS7ContentInfo *cinfo,
1.132 + SECCertUsage certusage,
1.133 + const SECItem *detached_digest,
1.134 + HASH_HashType digest_type,
1.135 + PRBool keepcerts);
1.136 +
1.137 +/*
1.138 + * SEC_PKCS7VerifyDetachedSignatureAtTime
1.139 + * Look at a PKCS7 contentInfo and check if the signature matches
1.140 + * a passed-in digest (calculated, supposedly, from detached contents).
1.141 + * The verification checks that the signing cert is valid and trusted
1.142 + * for the purpose specified by "certusage" at time "atTime".
1.143 + *
1.144 + * In addition, if "keepcerts" is true, add any new certificates found
1.145 + * into our local database.
1.146 + */
1.147 +extern PRBool
1.148 +SEC_PKCS7VerifyDetachedSignatureAtTime(SEC_PKCS7ContentInfo *cinfo,
1.149 + SECCertUsage certusage,
1.150 + const SECItem *detached_digest,
1.151 + HASH_HashType digest_type,
1.152 + PRBool keepcerts,
1.153 + PRTime atTime);
1.154 +
1.155 +/*
1.156 + * SEC_PKCS7GetSignerCommonName, SEC_PKCS7GetSignerEmailAddress
1.157 + * The passed-in contentInfo is espected to be Signed, and these
1.158 + * functions return the specified portion of the full signer name.
1.159 + *
1.160 + * Returns a pointer to allocated memory, which must be freed.
1.161 + * A NULL return value is an error.
1.162 + */
1.163 +extern char *SEC_PKCS7GetSignerCommonName(SEC_PKCS7ContentInfo *cinfo);
1.164 +extern char *SEC_PKCS7GetSignerEmailAddress(SEC_PKCS7ContentInfo *cinfo);
1.165 +
1.166 +/*
1.167 + * Return the the signing time, in UTCTime format, of a PKCS7 contentInfo.
1.168 + */
1.169 +extern SECItem *SEC_PKCS7GetSigningTime(SEC_PKCS7ContentInfo *cinfo);
1.170 +
1.171 +
1.172 +/************************************************************************
1.173 + * PKCS7 Creation and Encoding.
1.174 + ************************************************************************/
1.175 +
1.176 +/*
1.177 + * Start a PKCS7 signing context.
1.178 + *
1.179 + * "cert" is the cert that will be used to sign the data. It will be
1.180 + * checked for validity.
1.181 + *
1.182 + * "certusage" describes the signing usage (e.g. certUsageEmailSigner)
1.183 + * XXX Maybe SECCertUsage should be split so that our caller just says
1.184 + * "email" and *we* add the "signing" part -- otherwise our caller
1.185 + * could be lying about the usage; we do not want to allow encryption
1.186 + * certs for signing or vice versa.
1.187 + *
1.188 + * "certdb" is the cert database to use for verifying the cert.
1.189 + * It can be NULL if a default database is available (like in the client).
1.190 + *
1.191 + * "digestalg" names the digest algorithm (e.g. SEC_OID_SHA1).
1.192 + *
1.193 + * "digest" is the actual digest of the data. It must be provided in
1.194 + * the case of detached data or NULL if the content will be included.
1.195 + *
1.196 + * The return value can be passed to functions which add things to
1.197 + * it like attributes, then eventually to SEC_PKCS7Encode() or to
1.198 + * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
1.199 + * SEC_PKCS7DestroyContentInfo().
1.200 + *
1.201 + * An error results in a return value of NULL and an error set.
1.202 + * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
1.203 + */
1.204 +extern SEC_PKCS7ContentInfo *
1.205 +SEC_PKCS7CreateSignedData (CERTCertificate *cert,
1.206 + SECCertUsage certusage,
1.207 + CERTCertDBHandle *certdb,
1.208 + SECOidTag digestalg,
1.209 + SECItem *digest,
1.210 + SECKEYGetPasswordKey pwfn, void *pwfn_arg);
1.211 +
1.212 +/*
1.213 + * Create a PKCS7 certs-only container.
1.214 + *
1.215 + * "cert" is the (first) cert that will be included.
1.216 + *
1.217 + * "include_chain" specifies whether the entire chain for "cert" should
1.218 + * be included.
1.219 + *
1.220 + * "certdb" is the cert database to use for finding the chain.
1.221 + * It can be NULL in when "include_chain" is false, or when meaning
1.222 + * use the default database.
1.223 + *
1.224 + * More certs and chains can be added via AddCertficate and AddCertChain.
1.225 + *
1.226 + * An error results in a return value of NULL and an error set.
1.227 + * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
1.228 + */
1.229 +extern SEC_PKCS7ContentInfo *
1.230 +SEC_PKCS7CreateCertsOnly (CERTCertificate *cert,
1.231 + PRBool include_chain,
1.232 + CERTCertDBHandle *certdb);
1.233 +
1.234 +/*
1.235 + * Start a PKCS7 enveloping context.
1.236 + *
1.237 + * "cert" is the cert for the recipient. It will be checked for validity.
1.238 + *
1.239 + * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
1.240 + * XXX Maybe SECCertUsage should be split so that our caller just says
1.241 + * "email" and *we* add the "recipient" part -- otherwise our caller
1.242 + * could be lying about the usage; we do not want to allow encryption
1.243 + * certs for signing or vice versa.
1.244 + *
1.245 + * "certdb" is the cert database to use for verifying the cert.
1.246 + * It can be NULL if a default database is available (like in the client).
1.247 + *
1.248 + * "encalg" specifies the bulk encryption algorithm to use (e.g. SEC_OID_RC2).
1.249 + *
1.250 + * "keysize" specifies the bulk encryption key size, in bits.
1.251 + *
1.252 + * The return value can be passed to functions which add things to
1.253 + * it like more recipients, then eventually to SEC_PKCS7Encode() or to
1.254 + * SEC_PKCS7EncoderStart() to create the encoded data, and finally to
1.255 + * SEC_PKCS7DestroyContentInfo().
1.256 + *
1.257 + * An error results in a return value of NULL and an error set.
1.258 + * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
1.259 + */
1.260 +extern SEC_PKCS7ContentInfo *
1.261 +SEC_PKCS7CreateEnvelopedData (CERTCertificate *cert,
1.262 + SECCertUsage certusage,
1.263 + CERTCertDBHandle *certdb,
1.264 + SECOidTag encalg,
1.265 + int keysize,
1.266 + SECKEYGetPasswordKey pwfn, void *pwfn_arg);
1.267 +
1.268 +/*
1.269 + * XXX There will be a similar routine for creating signedAndEnvelopedData.
1.270 + * But its parameters will be different and I have no plans to implement
1.271 + * it any time soon because we have no current need for it.
1.272 + */
1.273 +
1.274 +/*
1.275 + * Create an empty PKCS7 data content info.
1.276 + *
1.277 + * An error results in a return value of NULL and an error set.
1.278 + * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
1.279 + */
1.280 +extern SEC_PKCS7ContentInfo *SEC_PKCS7CreateData (void);
1.281 +
1.282 +/*
1.283 + * Create an empty PKCS7 encrypted content info.
1.284 + *
1.285 + * "algorithm" specifies the bulk encryption algorithm to use.
1.286 + *
1.287 + * An error results in a return value of NULL and an error set.
1.288 + * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
1.289 + */
1.290 +extern SEC_PKCS7ContentInfo *
1.291 +SEC_PKCS7CreateEncryptedData (SECOidTag algorithm, int keysize,
1.292 + SECKEYGetPasswordKey pwfn, void *pwfn_arg);
1.293 +
1.294 +/*
1.295 + * All of the following things return SECStatus to signal success or failure.
1.296 + * Failure should have a more specific error status available via
1.297 + * PORT_GetError()/XP_GetError().
1.298 + */
1.299 +
1.300 +/*
1.301 + * Add the specified attribute to the authenticated (i.e. signed) attributes
1.302 + * of "cinfo" -- "oidtag" describes the attribute and "value" is the
1.303 + * value to be associated with it. NOTE! "value" must already be encoded;
1.304 + * no interpretation of "oidtag" is done. Also, it is assumed that this
1.305 + * signedData has only one signer -- if we ever need to add attributes
1.306 + * when there is more than one signature, we need a way to specify *which*
1.307 + * signature should get the attribute.
1.308 + *
1.309 + * XXX Technically, a signed attribute can have multiple values; if/when
1.310 + * we ever need to support an attribute which takes multiple values, we
1.311 + * either need to change this interface or create an AddSignedAttributeValue
1.312 + * which can be called subsequently, and would then append a value.
1.313 + *
1.314 + * "cinfo" should be of type signedData (the only kind of pkcs7 data
1.315 + * that is allowed authenticated attributes); SECFailure will be returned
1.316 + * if it is not.
1.317 + */
1.318 +extern SECStatus SEC_PKCS7AddSignedAttribute (SEC_PKCS7ContentInfo *cinfo,
1.319 + SECOidTag oidtag,
1.320 + SECItem *value);
1.321 +
1.322 +/*
1.323 + * Add "cert" and its entire chain to the set of certs included in "cinfo".
1.324 + *
1.325 + * "certdb" is the cert database to use for finding the chain.
1.326 + * It can be NULL, meaning use the default database.
1.327 + *
1.328 + * "cinfo" should be of type signedData or signedAndEnvelopedData;
1.329 + * SECFailure will be returned if it is not.
1.330 + */
1.331 +extern SECStatus SEC_PKCS7AddCertChain (SEC_PKCS7ContentInfo *cinfo,
1.332 + CERTCertificate *cert,
1.333 + CERTCertDBHandle *certdb);
1.334 +
1.335 +/*
1.336 + * Add "cert" to the set of certs included in "cinfo".
1.337 + *
1.338 + * "cinfo" should be of type signedData or signedAndEnvelopedData;
1.339 + * SECFailure will be returned if it is not.
1.340 + */
1.341 +extern SECStatus SEC_PKCS7AddCertificate (SEC_PKCS7ContentInfo *cinfo,
1.342 + CERTCertificate *cert);
1.343 +
1.344 +/*
1.345 + * Add another recipient to an encrypted message.
1.346 + *
1.347 + * "cinfo" should be of type envelopedData or signedAndEnvelopedData;
1.348 + * SECFailure will be returned if it is not.
1.349 + *
1.350 + * "cert" is the cert for the recipient. It will be checked for validity.
1.351 + *
1.352 + * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient)
1.353 + * XXX Maybe SECCertUsage should be split so that our caller just says
1.354 + * "email" and *we* add the "recipient" part -- otherwise our caller
1.355 + * could be lying about the usage; we do not want to allow encryption
1.356 + * certs for signing or vice versa.
1.357 + *
1.358 + * "certdb" is the cert database to use for verifying the cert.
1.359 + * It can be NULL if a default database is available (like in the client).
1.360 + */
1.361 +extern SECStatus SEC_PKCS7AddRecipient (SEC_PKCS7ContentInfo *cinfo,
1.362 + CERTCertificate *cert,
1.363 + SECCertUsage certusage,
1.364 + CERTCertDBHandle *certdb);
1.365 +
1.366 +/*
1.367 + * Add the signing time to the authenticated (i.e. signed) attributes
1.368 + * of "cinfo". This is expected to be included in outgoing signed
1.369 + * messages for email (S/MIME) but is likely useful in other situations.
1.370 + *
1.371 + * This should only be added once; a second call will either do
1.372 + * nothing or replace an old signing time with a newer one.
1.373 + *
1.374 + * XXX This will probably just shove the current time into "cinfo"
1.375 + * but it will not actually get signed until the entire item is
1.376 + * processed for encoding. Is this (expected to be small) delay okay?
1.377 + *
1.378 + * "cinfo" should be of type signedData (the only kind of pkcs7 data
1.379 + * that is allowed authenticated attributes); SECFailure will be returned
1.380 + * if it is not.
1.381 + */
1.382 +extern SECStatus SEC_PKCS7AddSigningTime (SEC_PKCS7ContentInfo *cinfo);
1.383 +
1.384 +/*
1.385 + * Add the signer's symmetric capabilities to the authenticated
1.386 + * (i.e. signed) attributes of "cinfo". This is expected to be
1.387 + * included in outgoing signed messages for email (S/MIME).
1.388 + *
1.389 + * This can only be added once; a second call will return SECFailure.
1.390 + *
1.391 + * "cinfo" should be of type signedData or signedAndEnvelopedData;
1.392 + * SECFailure will be returned if it is not.
1.393 + */
1.394 +extern SECStatus SEC_PKCS7AddSymmetricCapabilities(SEC_PKCS7ContentInfo *cinfo);
1.395 +
1.396 +/*
1.397 + * Mark that the signer's certificate and its issuing chain should
1.398 + * be included in the encoded data. This is expected to be used
1.399 + * in outgoing signed messages for email (S/MIME).
1.400 + *
1.401 + * "certdb" is the cert database to use for finding the chain.
1.402 + * It can be NULL, meaning use the default database.
1.403 + *
1.404 + * "cinfo" should be of type signedData or signedAndEnvelopedData;
1.405 + * SECFailure will be returned if it is not.
1.406 + */
1.407 +extern SECStatus SEC_PKCS7IncludeCertChain (SEC_PKCS7ContentInfo *cinfo,
1.408 + CERTCertDBHandle *certdb);
1.409 +
1.410 +
1.411 +/*
1.412 + * Set the content; it will be included and also hashed and/or encrypted
1.413 + * as appropriate. This is for in-memory content (expected to be "small")
1.414 + * that will be included in the PKCS7 object. All others should stream the
1.415 + * content through when encoding (see SEC_PKCS7Encoder{Start,Update,Finish}).
1.416 + *
1.417 + * "buf" points to data of length "len"; it will be copied.
1.418 + */
1.419 +extern SECStatus SEC_PKCS7SetContent (SEC_PKCS7ContentInfo *cinfo,
1.420 + const char *buf, unsigned long len);
1.421 +
1.422 +/*
1.423 + * Encode a PKCS7 object, in one shot. All necessary components
1.424 + * of the object must already be specified. Either the data has
1.425 + * already been included (via SetContent), or the data is detached,
1.426 + * or there is no data at all (certs-only).
1.427 + *
1.428 + * "cinfo" specifies the object to be encoded.
1.429 + *
1.430 + * "outputfn" is where the encoded bytes will be passed.
1.431 + *
1.432 + * "outputarg" is an opaque argument to the above callback.
1.433 + *
1.434 + * "bulkkey" specifies the bulk encryption key to use. This argument
1.435 + * can be NULL if no encryption is being done, or if the bulk key should
1.436 + * be generated internally (usually the case for EnvelopedData but never
1.437 + * for EncryptedData, which *must* provide a bulk encryption key).
1.438 + *
1.439 + * "pwfn" is a callback for getting the password which protects the
1.440 + * private key of the signer. This argument can be NULL if it is known
1.441 + * that no signing is going to be done.
1.442 + *
1.443 + * "pwfnarg" is an opaque argument to the above callback.
1.444 + */
1.445 +extern SECStatus SEC_PKCS7Encode (SEC_PKCS7ContentInfo *cinfo,
1.446 + SEC_PKCS7EncoderOutputCallback outputfn,
1.447 + void *outputarg,
1.448 + PK11SymKey *bulkkey,
1.449 + SECKEYGetPasswordKey pwfn,
1.450 + void *pwfnarg);
1.451 +
1.452 +/*
1.453 + * Encode a PKCS7 object, in one shot. All necessary components
1.454 + * of the object must already be specified. Either the data has
1.455 + * already been included (via SetContent), or the data is detached,
1.456 + * or there is no data at all (certs-only). The output, rather than
1.457 + * being passed to an output function as is done above, is all put
1.458 + * into a SECItem.
1.459 + *
1.460 + * "pool" specifies a pool from which to allocate the result.
1.461 + * It can be NULL, in which case memory is allocated generically.
1.462 + *
1.463 + * "dest" specifies a SECItem in which to put the result data.
1.464 + * It can be NULL, in which case the entire item is allocated, too.
1.465 + *
1.466 + * "cinfo" specifies the object to be encoded.
1.467 + *
1.468 + * "bulkkey" specifies the bulk encryption key to use. This argument
1.469 + * can be NULL if no encryption is being done, or if the bulk key should
1.470 + * be generated internally (usually the case for EnvelopedData but never
1.471 + * for EncryptedData, which *must* provide a bulk encryption key).
1.472 + *
1.473 + * "pwfn" is a callback for getting the password which protects the
1.474 + * private key of the signer. This argument can be NULL if it is known
1.475 + * that no signing is going to be done.
1.476 + *
1.477 + * "pwfnarg" is an opaque argument to the above callback.
1.478 + */
1.479 +extern SECItem *SEC_PKCS7EncodeItem (PLArenaPool *pool,
1.480 + SECItem *dest,
1.481 + SEC_PKCS7ContentInfo *cinfo,
1.482 + PK11SymKey *bulkkey,
1.483 + SECKEYGetPasswordKey pwfn,
1.484 + void *pwfnarg);
1.485 +
1.486 +/*
1.487 + * For those who want to simply point to the pkcs7 contentInfo ASN.1
1.488 + * template, and *not* call the encoding functions directly, the
1.489 + * following function can be used -- after it is called, the entire
1.490 + * PKCS7 contentInfo is ready to be encoded.
1.491 + */
1.492 +extern SECStatus SEC_PKCS7PrepareForEncode (SEC_PKCS7ContentInfo *cinfo,
1.493 + PK11SymKey *bulkkey,
1.494 + SECKEYGetPasswordKey pwfn,
1.495 + void *pwfnarg);
1.496 +
1.497 +/*
1.498 + * Start the process of encoding a PKCS7 object. The first part of
1.499 + * the encoded object will be passed to the output function right away;
1.500 + * after that it is expected that SEC_PKCS7EncoderUpdate will be called,
1.501 + * streaming in the actual content that is getting included as well as
1.502 + * signed or encrypted (or both).
1.503 + *
1.504 + * "cinfo" specifies the object to be encoded.
1.505 + *
1.506 + * "outputfn" is where the encoded bytes will be passed.
1.507 + *
1.508 + * "outputarg" is an opaque argument to the above callback.
1.509 + *
1.510 + * "bulkkey" specifies the bulk encryption key to use. This argument
1.511 + * can be NULL if no encryption is being done, or if the bulk key should
1.512 + * be generated internally (usually the case for EnvelopedData but never
1.513 + * for EncryptedData, which *must* provide a bulk encryption key).
1.514 + *
1.515 + * Returns an object to be passed to EncoderUpdate and EncoderFinish.
1.516 + */
1.517 +extern SEC_PKCS7EncoderContext *
1.518 +SEC_PKCS7EncoderStart (SEC_PKCS7ContentInfo *cinfo,
1.519 + SEC_PKCS7EncoderOutputCallback outputfn,
1.520 + void *outputarg,
1.521 + PK11SymKey *bulkkey);
1.522 +
1.523 +/*
1.524 + * Encode more contents, hashing and/or encrypting along the way.
1.525 + */
1.526 +extern SECStatus SEC_PKCS7EncoderUpdate (SEC_PKCS7EncoderContext *p7ecx,
1.527 + const char *buf,
1.528 + unsigned long len);
1.529 +
1.530 +/*
1.531 + * No more contents; finish the signature creation, if appropriate,
1.532 + * and then the encoding.
1.533 + *
1.534 + * "pwfn" is a callback for getting the password which protects the
1.535 + * signer's private key. This argument can be NULL if it is known
1.536 + * that no signing is going to be done.
1.537 + *
1.538 + * "pwfnarg" is an opaque argument to the above callback.
1.539 + */
1.540 +extern SECStatus SEC_PKCS7EncoderFinish (SEC_PKCS7EncoderContext *p7ecx,
1.541 + SECKEYGetPasswordKey pwfn,
1.542 + void *pwfnarg);
1.543 +
1.544 +/* Abort the underlying ASN.1 stream & set an error */
1.545 +void SEC_PKCS7EncoderAbort(SEC_PKCS7EncoderContext *p7dcx, int error);
1.546 +
1.547 +/* retrieve the algorithm ID used to encrypt the content info
1.548 + * for encrypted and enveloped data. The SECAlgorithmID pointer
1.549 + * returned needs to be freed as it is a copy of the algorithm
1.550 + * id in the content info.
1.551 + */
1.552 +extern SECAlgorithmID *
1.553 +SEC_PKCS7GetEncryptionAlgorithm(SEC_PKCS7ContentInfo *cinfo);
1.554 +
1.555 +/* the content of an encrypted data content info is encrypted.
1.556 + * it is assumed that for encrypted data, that the data has already
1.557 + * been set and is in the "plainContent" field of the content info.
1.558 + *
1.559 + * cinfo is the content info to encrypt
1.560 + *
1.561 + * key is the key with which to perform the encryption. if the
1.562 + * algorithm is a password based encryption algorithm, the
1.563 + * key is actually a password which will be processed per
1.564 + * PKCS #5.
1.565 + *
1.566 + * in the event of an error, SECFailure is returned. SECSuccess
1.567 + * indicates a success.
1.568 + */
1.569 +extern SECStatus
1.570 +SEC_PKCS7EncryptContents(PLArenaPool *poolp,
1.571 + SEC_PKCS7ContentInfo *cinfo,
1.572 + SECItem *key,
1.573 + void *wincx);
1.574 +
1.575 +/* the content of an encrypted data content info is decrypted.
1.576 + * it is assumed that for encrypted data, that the data has already
1.577 + * been set and is in the "encContent" field of the content info.
1.578 + *
1.579 + * cinfo is the content info to decrypt
1.580 + *
1.581 + * key is the key with which to perform the decryption. if the
1.582 + * algorithm is a password based encryption algorithm, the
1.583 + * key is actually a password which will be processed per
1.584 + * PKCS #5.
1.585 + *
1.586 + * in the event of an error, SECFailure is returned. SECSuccess
1.587 + * indicates a success.
1.588 + */
1.589 +extern SECStatus
1.590 +SEC_PKCS7DecryptContents(PLArenaPool *poolp,
1.591 + SEC_PKCS7ContentInfo *cinfo,
1.592 + SECItem *key,
1.593 + void *wincx);
1.594 +
1.595 +/* retrieve the certificate list from the content info. the list
1.596 + * is a pointer to the list in the content info. this should not
1.597 + * be deleted or freed in any way short of calling
1.598 + * SEC_PKCS7DestroyContentInfo
1.599 + */
1.600 +extern SECItem **
1.601 +SEC_PKCS7GetCertificateList(SEC_PKCS7ContentInfo *cinfo);
1.602 +
1.603 +/* Returns the key length (in bits) of the algorithm used to encrypt
1.604 + this object. Returns 0 if it's not encrypted, or the key length is
1.605 + irrelevant. */
1.606 +extern int
1.607 +SEC_PKCS7GetKeyLength(SEC_PKCS7ContentInfo *cinfo);
1.608 +
1.609 +
1.610 +/************************************************************************/
1.611 +SEC_END_PROTOS
1.612 +
1.613 +#endif /* _SECPKCS7_H_ */
