diff options
Diffstat (limited to 'security/nss/lib/pkcs7/secpkcs7.h')
| -rw-r--r-- | security/nss/lib/pkcs7/secpkcs7.h | 616 |
1 files changed, 616 insertions, 0 deletions
diff --git a/security/nss/lib/pkcs7/secpkcs7.h b/security/nss/lib/pkcs7/secpkcs7.h new file mode 100644 index 000000000..8c210225b --- /dev/null +++ b/security/nss/lib/pkcs7/secpkcs7.h @@ -0,0 +1,616 @@ +/* + * The contents of this file are subject to the Mozilla Public + * License Version 1.1 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS + * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or + * implied. See the License for the specific language governing + * rights and limitations under the License. + * + * The Original Code is the Netscape security libraries. + * + * The Initial Developer of the Original Code is Netscape + * Communications Corporation. Portions created by Netscape are + * Copyright (C) 1994-2000 Netscape Communications Corporation. All + * Rights Reserved. + * + * Contributor(s): + * + * Alternatively, the contents of this file may be used under the + * terms of the GNU General Public License Version 2 or later (the + * "GPL"), in which case the provisions of the GPL are applicable + * instead of those above. If you wish to allow use of your + * version of this file only under the terms of the GPL and not to + * allow others to use your version of this file under the MPL, + * indicate your decision by deleting the provisions above and + * replace them with the notice and other provisions required by + * the GPL. If you do not delete the provisions above, a recipient + * may use your version of this file under either the MPL or the + * GPL. + */ + +/* + * Interface to the PKCS7 implementation. + * + * $Id$ + */ + +#ifndef _SECPKCS7_H_ +#define _SECPKCS7_H_ + +#include "seccomon.h" + +#include "secoidt.h" +#include "certt.h" +#include "keyt.h" +#include "hasht.h" +#include "pkcs7t.h" + +extern const SEC_ASN1Template sec_PKCS7ContentInfoTemplate[]; + +/************************************************************************/ +SEC_BEGIN_PROTOS + +/************************************************************************ + * Miscellaneous + ************************************************************************/ + +/* + * Returns the content type of the given contentInfo. + */ +extern SECOidTag SEC_PKCS7ContentType (SEC_PKCS7ContentInfo *cinfo); + +/* + * Destroy a PKCS7 contentInfo and all of its sub-pieces. + */ +extern void SEC_PKCS7DestroyContentInfo(SEC_PKCS7ContentInfo *contentInfo); + +/* + * Copy a PKCS7 contentInfo. A Destroy is needed on *each* copy. + */ +extern SEC_PKCS7ContentInfo * +SEC_PKCS7CopyContentInfo(SEC_PKCS7ContentInfo *contentInfo); + +/* + * Return a pointer to the actual content. In the case of those types + * which are encrypted, this returns the *plain* content. + */ +extern SECItem *SEC_PKCS7GetContent(SEC_PKCS7ContentInfo *cinfo); + +/************************************************************************ + * PKCS7 Decoding, Verification, etc.. + ************************************************************************/ + +extern SEC_PKCS7DecoderContext * +SEC_PKCS7DecoderStart(SEC_PKCS7DecoderContentCallback callback, + void *callback_arg, + SECKEYGetPasswordKey pwfn, void *pwfn_arg, + SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, + void *decrypt_key_cb_arg, + SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb); + +extern SECStatus +SEC_PKCS7DecoderUpdate(SEC_PKCS7DecoderContext *p7dcx, + const char *buf, unsigned long len); + +extern SEC_PKCS7ContentInfo * +SEC_PKCS7DecoderFinish(SEC_PKCS7DecoderContext *p7dcx); + +extern SEC_PKCS7ContentInfo * +SEC_PKCS7DecodeItem(SECItem *p7item, + SEC_PKCS7DecoderContentCallback cb, void *cb_arg, + SECKEYGetPasswordKey pwfn, void *pwfn_arg, + SEC_PKCS7GetDecryptKeyCallback decrypt_key_cb, + void *decrypt_key_cb_arg, + SEC_PKCS7DecryptionAllowedCallback decrypt_allowed_cb); + +extern PRBool SEC_PKCS7ContainsCertsOrCrls(SEC_PKCS7ContentInfo *cinfo); + +/* checks to see if the contents of the content info is + * empty. it so, PR_TRUE is returned. PR_FALSE, otherwise. + * + * minLen is used to specify a minimum size. if content size <= minLen, + * content is assumed empty. + */ +extern PRBool +SEC_PKCS7IsContentEmpty(SEC_PKCS7ContentInfo *cinfo, unsigned int minLen); + +extern PRBool SEC_PKCS7ContentIsEncrypted(SEC_PKCS7ContentInfo *cinfo); + +/* + * If the PKCS7 content has a signature (not just *could* have a signature) + * return true; false otherwise. This can/should be called before calling + * VerifySignature, which will always indicate failure if no signature is + * present, but that does not mean there even was a signature! + * Note that the content itself can be empty (detached content was sent + * another way); it is the presence of the signature that matters. + */ +extern PRBool SEC_PKCS7ContentIsSigned(SEC_PKCS7ContentInfo *cinfo); + +/* + * SEC_PKCS7VerifySignature + * Look at a PKCS7 contentInfo and check if the signature is good. + * The verification checks that the signing cert is valid and trusted + * for the purpose specified by "certusage". + * + * In addition, if "keepcerts" is true, add any new certificates found + * into our local database. + */ +extern PRBool SEC_PKCS7VerifySignature(SEC_PKCS7ContentInfo *cinfo, + SECCertUsage certusage, + PRBool keepcerts); + +/* + * SEC_PKCS7VerifyDetachedSignature + * Look at a PKCS7 contentInfo and check if the signature matches + * a passed-in digest (calculated, supposedly, from detached contents). + * The verification checks that the signing cert is valid and trusted + * for the purpose specified by "certusage". + * + * In addition, if "keepcerts" is true, add any new certificates found + * into our local database. + */ +extern PRBool SEC_PKCS7VerifyDetachedSignature(SEC_PKCS7ContentInfo *cinfo, + SECCertUsage certusage, + SECItem *detached_digest, + HASH_HashType digest_type, + PRBool keepcerts); + +/* + * SEC_PKCS7GetSignerCommonName, SEC_PKCS7GetSignerEmailAddress + * The passed-in contentInfo is espected to be Signed, and these + * functions return the specified portion of the full signer name. + * + * Returns a pointer to allocated memory, which must be freed. + * A NULL return value is an error. + */ +extern char *SEC_PKCS7GetSignerCommonName(SEC_PKCS7ContentInfo *cinfo); +extern char *SEC_PKCS7GetSignerEmailAddress(SEC_PKCS7ContentInfo *cinfo); + +/* + * Return the the signing time, in UTCTime format, of a PKCS7 contentInfo. + */ +extern SECItem *SEC_PKCS7GetSigningTime(SEC_PKCS7ContentInfo *cinfo); + + +/************************************************************************ + * PKCS7 Creation and Encoding. + ************************************************************************/ + +/* + * Start a PKCS7 signing context. + * + * "cert" is the cert that will be used to sign the data. It will be + * checked for validity. + * + * "certusage" describes the signing usage (e.g. certUsageEmailSigner) + * XXX Maybe SECCertUsage should be split so that our caller just says + * "email" and *we* add the "signing" part -- otherwise our caller + * could be lying about the usage; we do not want to allow encryption + * certs for signing or vice versa. + * + * "certdb" is the cert database to use for verifying the cert. + * It can be NULL if a default database is available (like in the client). + * + * "digestalg" names the digest algorithm (e.g. SEC_OID_SHA1). + * + * "digest" is the actual digest of the data. It must be provided in + * the case of detached data or NULL if the content will be included. + * + * The return value can be passed to functions which add things to + * it like attributes, then eventually to SEC_PKCS7Encode() or to + * SEC_PKCS7EncoderStart() to create the encoded data, and finally to + * SEC_PKCS7DestroyContentInfo(). + * + * An error results in a return value of NULL and an error set. + * (Retrieve specific errors via PORT_GetError()/XP_GetError().) + */ +extern SEC_PKCS7ContentInfo * +SEC_PKCS7CreateSignedData (CERTCertificate *cert, + SECCertUsage certusage, + CERTCertDBHandle *certdb, + SECOidTag digestalg, + SECItem *digest, + SECKEYGetPasswordKey pwfn, void *pwfn_arg); + +/* + * Create a PKCS7 certs-only container. + * + * "cert" is the (first) cert that will be included. + * + * "include_chain" specifies whether the entire chain for "cert" should + * be included. + * + * "certdb" is the cert database to use for finding the chain. + * It can be NULL in when "include_chain" is false, or when meaning + * use the default database. + * + * More certs and chains can be added via AddCertficate and AddCertChain. + * + * An error results in a return value of NULL and an error set. + * (Retrieve specific errors via PORT_GetError()/XP_GetError().) + */ +extern SEC_PKCS7ContentInfo * +SEC_PKCS7CreateCertsOnly (CERTCertificate *cert, + PRBool include_chain, + CERTCertDBHandle *certdb); + +/* + * Start a PKCS7 enveloping context. + * + * "cert" is the cert for the recipient. It will be checked for validity. + * + * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient) + * XXX Maybe SECCertUsage should be split so that our caller just says + * "email" and *we* add the "recipient" part -- otherwise our caller + * could be lying about the usage; we do not want to allow encryption + * certs for signing or vice versa. + * + * "certdb" is the cert database to use for verifying the cert. + * It can be NULL if a default database is available (like in the client). + * + * "encalg" specifies the bulk encryption algorithm to use (e.g. SEC_OID_RC2). + * + * "keysize" specifies the bulk encryption key size, in bits. + * + * The return value can be passed to functions which add things to + * it like more recipients, then eventually to SEC_PKCS7Encode() or to + * SEC_PKCS7EncoderStart() to create the encoded data, and finally to + * SEC_PKCS7DestroyContentInfo(). + * + * An error results in a return value of NULL and an error set. + * (Retrieve specific errors via PORT_GetError()/XP_GetError().) + */ +extern SEC_PKCS7ContentInfo * +SEC_PKCS7CreateEnvelopedData (CERTCertificate *cert, + SECCertUsage certusage, + CERTCertDBHandle *certdb, + SECOidTag encalg, + int keysize, + SECKEYGetPasswordKey pwfn, void *pwfn_arg); + +/* + * XXX There will be a similar routine for creating signedAndEnvelopedData. + * But its parameters will be different and I have no plans to implement + * it any time soon because we have no current need for it. + */ + +/* + * Create an empty PKCS7 data content info. + * + * An error results in a return value of NULL and an error set. + * (Retrieve specific errors via PORT_GetError()/XP_GetError().) + */ +extern SEC_PKCS7ContentInfo *SEC_PKCS7CreateData (void); + +/* + * Create an empty PKCS7 encrypted content info. + * + * "algorithm" specifies the bulk encryption algorithm to use. + * + * An error results in a return value of NULL and an error set. + * (Retrieve specific errors via PORT_GetError()/XP_GetError().) + */ +extern SEC_PKCS7ContentInfo * +SEC_PKCS7CreateEncryptedData (SECOidTag algorithm, int keysize, + SECKEYGetPasswordKey pwfn, void *pwfn_arg); + +/* + * All of the following things return SECStatus to signal success or failure. + * Failure should have a more specific error status available via + * PORT_GetError()/XP_GetError(). + */ + +/* + * Add the specified attribute to the authenticated (i.e. signed) attributes + * of "cinfo" -- "oidtag" describes the attribute and "value" is the + * value to be associated with it. NOTE! "value" must already be encoded; + * no interpretation of "oidtag" is done. Also, it is assumed that this + * signedData has only one signer -- if we ever need to add attributes + * when there is more than one signature, we need a way to specify *which* + * signature should get the attribute. + * + * XXX Technically, a signed attribute can have multiple values; if/when + * we ever need to support an attribute which takes multiple values, we + * either need to change this interface or create an AddSignedAttributeValue + * which can be called subsequently, and would then append a value. + * + * "cinfo" should be of type signedData (the only kind of pkcs7 data + * that is allowed authenticated attributes); SECFailure will be returned + * if it is not. + */ +extern SECStatus SEC_PKCS7AddSignedAttribute (SEC_PKCS7ContentInfo *cinfo, + SECOidTag oidtag, + SECItem *value); + +/* + * Add "cert" and its entire chain to the set of certs included in "cinfo". + * + * "certdb" is the cert database to use for finding the chain. + * It can be NULL, meaning use the default database. + * + * "cinfo" should be of type signedData or signedAndEnvelopedData; + * SECFailure will be returned if it is not. + */ +extern SECStatus SEC_PKCS7AddCertChain (SEC_PKCS7ContentInfo *cinfo, + CERTCertificate *cert, + CERTCertDBHandle *certdb); + +/* + * Add "cert" to the set of certs included in "cinfo". + * + * "cinfo" should be of type signedData or signedAndEnvelopedData; + * SECFailure will be returned if it is not. + */ +extern SECStatus SEC_PKCS7AddCertificate (SEC_PKCS7ContentInfo *cinfo, + CERTCertificate *cert); + +/* + * Add another recipient to an encrypted message. + * + * "cinfo" should be of type envelopedData or signedAndEnvelopedData; + * SECFailure will be returned if it is not. + * + * "cert" is the cert for the recipient. It will be checked for validity. + * + * "certusage" describes the encryption usage (e.g. certUsageEmailRecipient) + * XXX Maybe SECCertUsage should be split so that our caller just says + * "email" and *we* add the "recipient" part -- otherwise our caller + * could be lying about the usage; we do not want to allow encryption + * certs for signing or vice versa. + * + * "certdb" is the cert database to use for verifying the cert. + * It can be NULL if a default database is available (like in the client). + */ +extern SECStatus SEC_PKCS7AddRecipient (SEC_PKCS7ContentInfo *cinfo, + CERTCertificate *cert, + SECCertUsage certusage, + CERTCertDBHandle *certdb); + +/* + * Add the signing time to the authenticated (i.e. signed) attributes + * of "cinfo". This is expected to be included in outgoing signed + * messages for email (S/MIME) but is likely useful in other situations. + * + * This should only be added once; a second call will either do + * nothing or replace an old signing time with a newer one. + * + * XXX This will probably just shove the current time into "cinfo" + * but it will not actually get signed until the entire item is + * processed for encoding. Is this (expected to be small) delay okay? + * + * "cinfo" should be of type signedData (the only kind of pkcs7 data + * that is allowed authenticated attributes); SECFailure will be returned + * if it is not. + */ +extern SECStatus SEC_PKCS7AddSigningTime (SEC_PKCS7ContentInfo *cinfo); + +/* + * Add the signer's symmetric capabilities to the authenticated + * (i.e. signed) attributes of "cinfo". This is expected to be + * included in outgoing signed messages for email (S/MIME). + * + * This can only be added once; a second call will return SECFailure. + * + * "cinfo" should be of type signedData or signedAndEnvelopedData; + * SECFailure will be returned if it is not. + */ +extern SECStatus SEC_PKCS7AddSymmetricCapabilities(SEC_PKCS7ContentInfo *cinfo); + +/* + * Mark that the signer's certificate and its issuing chain should + * be included in the encoded data. This is expected to be used + * in outgoing signed messages for email (S/MIME). + * + * "certdb" is the cert database to use for finding the chain. + * It can be NULL, meaning use the default database. + * + * "cinfo" should be of type signedData or signedAndEnvelopedData; + * SECFailure will be returned if it is not. + */ +extern SECStatus SEC_PKCS7IncludeCertChain (SEC_PKCS7ContentInfo *cinfo, + CERTCertDBHandle *certdb); + + +/* + * Set the content; it will be included and also hashed and/or encrypted + * as appropriate. This is for in-memory content (expected to be "small") + * that will be included in the PKCS7 object. All others should stream the + * content through when encoding (see SEC_PKCS7Encoder{Start,Update,Finish}). + * + * "buf" points to data of length "len"; it will be copied. + */ +extern SECStatus SEC_PKCS7SetContent (SEC_PKCS7ContentInfo *cinfo, + const char *buf, unsigned long len); + +/* + * Encode a PKCS7 object, in one shot. All necessary components + * of the object must already be specified. Either the data has + * already been included (via SetContent), or the data is detached, + * or there is no data at all (certs-only). + * + * "cinfo" specifies the object to be encoded. + * + * "outputfn" is where the encoded bytes will be passed. + * + * "outputarg" is an opaque argument to the above callback. + * + * "bulkkey" specifies the bulk encryption key to use. This argument + * can be NULL if no encryption is being done, or if the bulk key should + * be generated internally (usually the case for EnvelopedData but never + * for EncryptedData, which *must* provide a bulk encryption key). + * + * "pwfn" is a callback for getting the password which protects the + * private key of the signer. This argument can be NULL if it is known + * that no signing is going to be done. + * + * "pwfnarg" is an opaque argument to the above callback. + */ +extern SECStatus SEC_PKCS7Encode (SEC_PKCS7ContentInfo *cinfo, + SEC_PKCS7EncoderOutputCallback outputfn, + void *outputarg, + PK11SymKey *bulkkey, + SECKEYGetPasswordKey pwfn, + void *pwfnarg); + +/* + * Encode a PKCS7 object, in one shot. All necessary components + * of the object must already be specified. Either the data has + * already been included (via SetContent), or the data is detached, + * or there is no data at all (certs-only). The output, rather than + * being passed to an output function as is done above, is all put + * into a SECItem. + * + * "pool" specifies a pool from which to allocate the result. + * It can be NULL, in which case memory is allocated generically. + * + * "dest" specifies a SECItem in which to put the result data. + * It can be NULL, in which case the entire item is allocated, too. + * + * "cinfo" specifies the object to be encoded. + * + * "bulkkey" specifies the bulk encryption key to use. This argument + * can be NULL if no encryption is being done, or if the bulk key should + * be generated internally (usually the case for EnvelopedData but never + * for EncryptedData, which *must* provide a bulk encryption key). + * + * "pwfn" is a callback for getting the password which protects the + * private key of the signer. This argument can be NULL if it is known + * that no signing is going to be done. + * + * "pwfnarg" is an opaque argument to the above callback. + */ +extern SECItem *SEC_PKCS7EncodeItem (PRArenaPool *pool, + SECItem *dest, + SEC_PKCS7ContentInfo *cinfo, + PK11SymKey *bulkkey, + SECKEYGetPasswordKey pwfn, + void *pwfnarg); + +/* + * For those who want to simply point to the pkcs7 contentInfo ASN.1 + * template, and *not* call the encoding functions directly, the + * following function can be used -- after it is called, the entire + * PKCS7 contentInfo is ready to be encoded. + */ +extern SECStatus SEC_PKCS7PrepareForEncode (SEC_PKCS7ContentInfo *cinfo, + PK11SymKey *bulkkey, + SECKEYGetPasswordKey pwfn, + void *pwfnarg); + +/* + * Start the process of encoding a PKCS7 object. The first part of + * the encoded object will be passed to the output function right away; + * after that it is expected that SEC_PKCS7EncoderUpdate will be called, + * streaming in the actual content that is getting included as well as + * signed or encrypted (or both). + * + * "cinfo" specifies the object to be encoded. + * + * "outputfn" is where the encoded bytes will be passed. + * + * "outputarg" is an opaque argument to the above callback. + * + * "bulkkey" specifies the bulk encryption key to use. This argument + * can be NULL if no encryption is being done, or if the bulk key should + * be generated internally (usually the case for EnvelopedData but never + * for EncryptedData, which *must* provide a bulk encryption key). + * + * Returns an object to be passed to EncoderUpdate and EncoderFinish. + */ +extern SEC_PKCS7EncoderContext * +SEC_PKCS7EncoderStart (SEC_PKCS7ContentInfo *cinfo, + SEC_PKCS7EncoderOutputCallback outputfn, + void *outputarg, + PK11SymKey *bulkkey); + +/* + * Encode more contents, hashing and/or encrypting along the way. + */ +extern SECStatus SEC_PKCS7EncoderUpdate (SEC_PKCS7EncoderContext *p7ecx, + const char *buf, + unsigned long len); + +/* + * No more contents; finish the signature creation, if appropriate, + * and then the encoding. + * + * "pwfn" is a callback for getting the password which protects the + * signer's private key. This argument can be NULL if it is known + * that no signing is going to be done. + * + * "pwfnarg" is an opaque argument to the above callback. + */ +extern SECStatus SEC_PKCS7EncoderFinish (SEC_PKCS7EncoderContext *p7ecx, + SECKEYGetPasswordKey pwfn, + void *pwfnarg); + +/* retrieve the algorithm ID used to encrypt the content info + * for encrypted and enveloped data. The SECAlgorithmID pointer + * returned needs to be freed as it is a copy of the algorithm + * id in the content info. + */ +extern SECAlgorithmID * +SEC_PKCS7GetEncryptionAlgorithm(SEC_PKCS7ContentInfo *cinfo); + +/* the content of an encrypted data content info is encrypted. + * it is assumed that for encrypted data, that the data has already + * been set and is in the "plainContent" field of the content info. + * + * cinfo is the content info to encrypt + * + * key is the key with which to perform the encryption. if the + * algorithm is a password based encryption algorithm, the + * key is actually a password which will be processed per + * PKCS #5. + * + * in the event of an error, SECFailure is returned. SECSuccess + * indicates a success. + */ +extern SECStatus +SEC_PKCS7EncryptContents(PRArenaPool *poolp, + SEC_PKCS7ContentInfo *cinfo, + SECItem *key, + void *wincx); + +/* the content of an encrypted data content info is decrypted. + * it is assumed that for encrypted data, that the data has already + * been set and is in the "encContent" field of the content info. + * + * cinfo is the content info to decrypt + * + * key is the key with which to perform the decryption. if the + * algorithm is a password based encryption algorithm, the + * key is actually a password which will be processed per + * PKCS #5. + * + * in the event of an error, SECFailure is returned. SECSuccess + * indicates a success. + */ +extern SECStatus +SEC_PKCS7DecryptContents(PRArenaPool *poolp, + SEC_PKCS7ContentInfo *cinfo, + SECItem *key, + void *wincx); + +/* retrieve the certificate list from the content info. the list + * is a pointer to the list in the content info. this should not + * be deleted or freed in any way short of calling + * SEC_PKCS7DestroyContentInfo + */ +extern SECItem ** +SEC_PKCS7GetCertificateList(SEC_PKCS7ContentInfo *cinfo); + +/* Returns the key length (in bits) of the algorithm used to encrypt + this object. Returns 0 if it's not encrypted, or the key length is + irrelevant. */ +extern int +SEC_PKCS7GetKeyLength(SEC_PKCS7ContentInfo *cinfo); + + +/************************************************************************/ +SEC_END_PROTOS + +#endif /* _SECPKCS7_H_ */ |