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