secpkcs7.h

来自「支持SSL v2/v3, TLS, PKCS #5, PKCS #7, PKCS」· C头文件 代码 · 共 619 行 · 第 1/2 页

/*
 * 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: secpkcs7.h,v 1.1 2000/03/31 19:16:09 relyea%netscape.com Exp $
 */

#ifndef _SECPKCS7_H_
#define _SECPKCS7_H_

#include "seccomon.h"
#include "mcom_db.h"	/* needed by certt.h */

#include "secoidt.h"
#include "secder.h"	/* needed by certt.h; XXX go away when possible */
#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