secpkcs7.h

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

 * 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_ */