/gecko_api/include/cms.h

http://firefox-mac-pdf.googlecode.com/ · C Header · 1134 lines · 349 code · 170 blank · 615 comment · 0 complexity · 2c33034ad53faacd447890c6efa011e7 MD5 · raw file

  1. /* ***** BEGIN LICENSE BLOCK *****
  2. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3. *
  4. * The contents of this file are subject to the Mozilla Public License Version
  5. * 1.1 (the "License"); you may not use this file except in compliance with
  6. * the License. You may obtain a copy of the License at
  7. * http://www.mozilla.org/MPL/
  8. *
  9. * Software distributed under the License is distributed on an "AS IS" basis,
  10. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11. * for the specific language governing rights and limitations under the
  12. * License.
  13. *
  14. * The Original Code is the Netscape security libraries.
  15. *
  16. * The Initial Developer of the Original Code is
  17. * Netscape Communications Corporation.
  18. * Portions created by the Initial Developer are Copyright (C) 1994-2000
  19. * the Initial Developer. All Rights Reserved.
  20. *
  21. * Contributor(s):
  22. *
  23. * Alternatively, the contents of this file may be used under the terms of
  24. * either the GNU General Public License Version 2 or later (the "GPL"), or
  25. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  26. * in which case the provisions of the GPL or the LGPL are applicable instead
  27. * of those above. If you wish to allow use of your version of this file only
  28. * under the terms of either the GPL or the LGPL, and not to allow others to
  29. * use your version of this file under the terms of the MPL, indicate your
  30. * decision by deleting the provisions above and replace them with the notice
  31. * and other provisions required by the GPL or the LGPL. If you do not delete
  32. * the provisions above, a recipient may use your version of this file under
  33. * the terms of any one of the MPL, the GPL or the LGPL.
  34. *
  35. * ***** END LICENSE BLOCK ***** */
  36. /*
  37. * Interfaces of the CMS implementation.
  38. *
  39. * $Id: cms.h,v 1.21 2006/02/08 06:13:43 rrelyea%redhat.com Exp $
  40. */
  41. #ifndef _CMS_H_
  42. #define _CMS_H_
  43. #include "seccomon.h"
  44. #include "secoidt.h"
  45. #include "certt.h"
  46. #include "keyt.h"
  47. #include "hasht.h"
  48. #include "cmst.h"
  49. /************************************************************************/
  50. SEC_BEGIN_PROTOS
  51. /************************************************************************
  52. * cmsdecode.c - CMS decoding
  53. ************************************************************************/
  54. /*
  55. * NSS_CMSDecoder_Start - set up decoding of a DER-encoded CMS message
  56. *
  57. * "poolp" - pointer to arena for message, or NULL if new pool should be created
  58. * "cb", "cb_arg" - callback function and argument for delivery of inner content
  59. * inner content will be stored in the message if cb is NULL.
  60. * "pwfn", pwfn_arg" - callback function for getting token password
  61. * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
  62. */
  63. extern NSSCMSDecoderContext *
  64. NSS_CMSDecoder_Start(PRArenaPool *poolp,
  65. NSSCMSContentCallback cb, void *cb_arg,
  66. PK11PasswordFunc pwfn, void *pwfn_arg,
  67. NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg);
  68. /*
  69. * NSS_CMSDecoder_Update - feed DER-encoded data to decoder
  70. */
  71. extern SECStatus
  72. NSS_CMSDecoder_Update(NSSCMSDecoderContext *p7dcx, const char *buf, unsigned long len);
  73. /*
  74. * NSS_CMSDecoder_Cancel - cancel a decoding process
  75. */
  76. extern void
  77. NSS_CMSDecoder_Cancel(NSSCMSDecoderContext *p7dcx);
  78. /*
  79. * NSS_CMSDecoder_Finish - mark the end of inner content and finish decoding
  80. */
  81. extern NSSCMSMessage *
  82. NSS_CMSDecoder_Finish(NSSCMSDecoderContext *p7dcx);
  83. /*
  84. * NSS_CMSMessage_CreateFromDER - decode a CMS message from DER encoded data
  85. */
  86. extern NSSCMSMessage *
  87. NSS_CMSMessage_CreateFromDER(SECItem *DERmessage,
  88. NSSCMSContentCallback cb, void *cb_arg,
  89. PK11PasswordFunc pwfn, void *pwfn_arg,
  90. NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg);
  91. /************************************************************************
  92. * cmsencode.c - CMS encoding
  93. ************************************************************************/
  94. /*
  95. * NSS_CMSEncoder_Start - set up encoding of a CMS message
  96. *
  97. * "cmsg" - message to encode
  98. * "outputfn", "outputarg" - callback function for delivery of DER-encoded output
  99. * will not be called if NULL.
  100. * "dest" - if non-NULL, pointer to SECItem that will hold the DER-encoded output
  101. * "destpoolp" - pool to allocate DER-encoded output in
  102. * "pwfn", pwfn_arg" - callback function for getting token password
  103. * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
  104. * "detached_digestalgs", "detached_digests" - digests from detached content
  105. */
  106. extern NSSCMSEncoderContext *
  107. NSS_CMSEncoder_Start(NSSCMSMessage *cmsg,
  108. NSSCMSContentCallback outputfn, void *outputarg,
  109. SECItem *dest, PLArenaPool *destpoolp,
  110. PK11PasswordFunc pwfn, void *pwfn_arg,
  111. NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
  112. SECAlgorithmID **detached_digestalgs, SECItem **detached_digests);
  113. /*
  114. * NSS_CMSEncoder_Update - take content data delivery from the user
  115. *
  116. * "p7ecx" - encoder context
  117. * "data" - content data
  118. * "len" - length of content data
  119. */
  120. extern SECStatus
  121. NSS_CMSEncoder_Update(NSSCMSEncoderContext *p7ecx, const char *data, unsigned long len);
  122. /*
  123. * NSS_CMSEncoder_Cancel - stop all encoding
  124. */
  125. extern SECStatus
  126. NSS_CMSEncoder_Cancel(NSSCMSEncoderContext *p7ecx);
  127. /*
  128. * NSS_CMSEncoder_Finish - signal the end of data
  129. *
  130. * we need to walk down the chain of encoders and the finish them from the innermost out
  131. */
  132. extern SECStatus
  133. NSS_CMSEncoder_Finish(NSSCMSEncoderContext *p7ecx);
  134. /************************************************************************
  135. * cmsmessage.c - CMS message object
  136. ************************************************************************/
  137. /*
  138. * NSS_CMSMessage_Create - create a CMS message object
  139. *
  140. * "poolp" - arena to allocate memory from, or NULL if new arena should be created
  141. */
  142. extern NSSCMSMessage *
  143. NSS_CMSMessage_Create(PLArenaPool *poolp);
  144. /*
  145. * NSS_CMSMessage_SetEncodingParams - set up a CMS message object for encoding or decoding
  146. *
  147. * "cmsg" - message object
  148. * "pwfn", pwfn_arg" - callback function for getting token password
  149. * "decrypt_key_cb", "decrypt_key_cb_arg" - callback function for getting bulk key for encryptedData
  150. * "detached_digestalgs", "detached_digests" - digests from detached content
  151. *
  152. * used internally.
  153. */
  154. extern void
  155. NSS_CMSMessage_SetEncodingParams(NSSCMSMessage *cmsg,
  156. PK11PasswordFunc pwfn, void *pwfn_arg,
  157. NSSCMSGetDecryptKeyCallback decrypt_key_cb, void *decrypt_key_cb_arg,
  158. SECAlgorithmID **detached_digestalgs, SECItem **detached_digests);
  159. /*
  160. * NSS_CMSMessage_Destroy - destroy a CMS message and all of its sub-pieces.
  161. */
  162. extern void
  163. NSS_CMSMessage_Destroy(NSSCMSMessage *cmsg);
  164. /*
  165. * NSS_CMSMessage_Copy - return a copy of the given message.
  166. *
  167. * The copy may be virtual or may be real -- either way, the result needs
  168. * to be passed to NSS_CMSMessage_Destroy later (as does the original).
  169. */
  170. extern NSSCMSMessage *
  171. NSS_CMSMessage_Copy(NSSCMSMessage *cmsg);
  172. /*
  173. * NSS_CMSMessage_GetArena - return a pointer to the message's arena pool
  174. */
  175. extern PLArenaPool *
  176. NSS_CMSMessage_GetArena(NSSCMSMessage *cmsg);
  177. /*
  178. * NSS_CMSMessage_GetContentInfo - return a pointer to the top level contentInfo
  179. */
  180. extern NSSCMSContentInfo *
  181. NSS_CMSMessage_GetContentInfo(NSSCMSMessage *cmsg);
  182. /*
  183. * Return a pointer to the actual content.
  184. * In the case of those types which are encrypted, this returns the *plain* content.
  185. * In case of nested contentInfos, this descends and retrieves the innermost content.
  186. */
  187. extern SECItem *
  188. NSS_CMSMessage_GetContent(NSSCMSMessage *cmsg);
  189. /*
  190. * NSS_CMSMessage_ContentLevelCount - count number of levels of CMS content objects in this message
  191. *
  192. * CMS data content objects do not count.
  193. */
  194. extern int
  195. NSS_CMSMessage_ContentLevelCount(NSSCMSMessage *cmsg);
  196. /*
  197. * NSS_CMSMessage_ContentLevel - find content level #n
  198. *
  199. * CMS data content objects do not count.
  200. */
  201. extern NSSCMSContentInfo *
  202. NSS_CMSMessage_ContentLevel(NSSCMSMessage *cmsg, int n);
  203. /*
  204. * NSS_CMSMessage_ContainsCertsOrCrls - see if message contains certs along the way
  205. */
  206. extern PRBool
  207. NSS_CMSMessage_ContainsCertsOrCrls(NSSCMSMessage *cmsg);
  208. /*
  209. * NSS_CMSMessage_IsEncrypted - see if message contains a encrypted submessage
  210. */
  211. extern PRBool
  212. NSS_CMSMessage_IsEncrypted(NSSCMSMessage *cmsg);
  213. /*
  214. * NSS_CMSMessage_IsSigned - see if message contains a signed submessage
  215. *
  216. * If the CMS message has a SignedData with a signature (not just a SignedData)
  217. * return true; false otherwise. This can/should be called before calling
  218. * VerifySignature, which will always indicate failure if no signature is
  219. * present, but that does not mean there even was a signature!
  220. * Note that the content itself can be empty (detached content was sent
  221. * another way); it is the presence of the signature that matters.
  222. */
  223. extern PRBool
  224. NSS_CMSMessage_IsSigned(NSSCMSMessage *cmsg);
  225. /*
  226. * NSS_CMSMessage_IsContentEmpty - see if content is empty
  227. *
  228. * returns PR_TRUE is innermost content length is < minLen
  229. * XXX need the encrypted content length (why?)
  230. */
  231. extern PRBool
  232. NSS_CMSMessage_IsContentEmpty(NSSCMSMessage *cmsg, unsigned int minLen);
  233. /************************************************************************
  234. * cmscinfo.c - CMS contentInfo methods
  235. ************************************************************************/
  236. /*
  237. * NSS_CMSContentInfo_Destroy - destroy a CMS contentInfo and all of its sub-pieces.
  238. */
  239. extern void
  240. NSS_CMSContentInfo_Destroy(NSSCMSContentInfo *cinfo);
  241. /*
  242. * NSS_CMSContentInfo_GetChildContentInfo - get content's contentInfo (if it exists)
  243. */
  244. extern NSSCMSContentInfo *
  245. NSS_CMSContentInfo_GetChildContentInfo(NSSCMSContentInfo *cinfo);
  246. /*
  247. * NSS_CMSContentInfo_SetContent - set cinfo's content type & content to CMS object
  248. */
  249. extern SECStatus
  250. NSS_CMSContentInfo_SetContent(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECOidTag type, void *ptr);
  251. /*
  252. * NSS_CMSContentInfo_SetContent_XXXX - typesafe wrappers for NSS_CMSContentInfo_SetType
  253. * set cinfo's content type & content to CMS object
  254. */
  255. extern SECStatus
  256. NSS_CMSContentInfo_SetContent_Data(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, SECItem *data, PRBool detached);
  257. extern SECStatus
  258. NSS_CMSContentInfo_SetContent_SignedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSSignedData *sigd);
  259. extern SECStatus
  260. NSS_CMSContentInfo_SetContent_EnvelopedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEnvelopedData *envd);
  261. extern SECStatus
  262. NSS_CMSContentInfo_SetContent_DigestedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSDigestedData *digd);
  263. extern SECStatus
  264. NSS_CMSContentInfo_SetContent_EncryptedData(NSSCMSMessage *cmsg, NSSCMSContentInfo *cinfo, NSSCMSEncryptedData *encd);
  265. /*
  266. * NSS_CMSContentInfo_GetContent - get pointer to inner content
  267. *
  268. * needs to be casted...
  269. */
  270. extern void *
  271. NSS_CMSContentInfo_GetContent(NSSCMSContentInfo *cinfo);
  272. /*
  273. * NSS_CMSContentInfo_GetInnerContent - get pointer to innermost content
  274. *
  275. * this is typically only called by NSS_CMSMessage_GetContent()
  276. */
  277. extern SECItem *
  278. NSS_CMSContentInfo_GetInnerContent(NSSCMSContentInfo *cinfo);
  279. /*
  280. * NSS_CMSContentInfo_GetContentType{Tag,OID} - find out (saving pointer to lookup result
  281. * for future reference) and return the inner content type.
  282. */
  283. extern SECOidTag
  284. NSS_CMSContentInfo_GetContentTypeTag(NSSCMSContentInfo *cinfo);
  285. extern SECItem *
  286. NSS_CMSContentInfo_GetContentTypeOID(NSSCMSContentInfo *cinfo);
  287. /*
  288. * NSS_CMSContentInfo_GetContentEncAlgTag - find out (saving pointer to lookup result
  289. * for future reference) and return the content encryption algorithm tag.
  290. */
  291. extern SECOidTag
  292. NSS_CMSContentInfo_GetContentEncAlgTag(NSSCMSContentInfo *cinfo);
  293. /*
  294. * NSS_CMSContentInfo_GetContentEncAlg - find out and return the content encryption algorithm tag.
  295. */
  296. extern SECAlgorithmID *
  297. NSS_CMSContentInfo_GetContentEncAlg(NSSCMSContentInfo *cinfo);
  298. extern SECStatus
  299. NSS_CMSContentInfo_SetContentEncAlg(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
  300. SECOidTag bulkalgtag, SECItem *parameters, int keysize);
  301. extern SECStatus
  302. NSS_CMSContentInfo_SetContentEncAlgID(PLArenaPool *poolp, NSSCMSContentInfo *cinfo,
  303. SECAlgorithmID *algid, int keysize);
  304. extern void
  305. NSS_CMSContentInfo_SetBulkKey(NSSCMSContentInfo *cinfo, PK11SymKey *bulkkey);
  306. extern PK11SymKey *
  307. NSS_CMSContentInfo_GetBulkKey(NSSCMSContentInfo *cinfo);
  308. extern int
  309. NSS_CMSContentInfo_GetBulkKeySize(NSSCMSContentInfo *cinfo);
  310. /************************************************************************
  311. * cmsutil.c - CMS misc utility functions
  312. ************************************************************************/
  313. /*
  314. * NSS_CMSArray_SortByDER - sort array of objects by objects' DER encoding
  315. *
  316. * make sure that the order of the objects guarantees valid DER (which must be
  317. * in lexigraphically ascending order for a SET OF); if reordering is necessary it
  318. * will be done in place (in objs).
  319. */
  320. extern SECStatus
  321. NSS_CMSArray_SortByDER(void **objs, const SEC_ASN1Template *objtemplate, void **objs2);
  322. /*
  323. * NSS_CMSUtil_DERCompare - for use with NSS_CMSArray_Sort to
  324. * sort arrays of SECItems containing DER
  325. */
  326. extern int
  327. NSS_CMSUtil_DERCompare(void *a, void *b);
  328. /*
  329. * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
  330. * algorithms.
  331. *
  332. * algorithmArray - array of algorithm IDs
  333. * algid - algorithmid of algorithm to pick
  334. *
  335. * Returns:
  336. * An integer containing the index of the algorithm in the array or -1 if
  337. * algorithm was not found.
  338. */
  339. extern int
  340. NSS_CMSAlgArray_GetIndexByAlgID(SECAlgorithmID **algorithmArray, SECAlgorithmID *algid);
  341. /*
  342. * NSS_CMSAlgArray_GetIndexByAlgID - find a specific algorithm in an array of
  343. * algorithms.
  344. *
  345. * algorithmArray - array of algorithm IDs
  346. * algiddata - id of algorithm to pick
  347. *
  348. * Returns:
  349. * An integer containing the index of the algorithm in the array or -1 if
  350. * algorithm was not found.
  351. */
  352. extern int
  353. NSS_CMSAlgArray_GetIndexByAlgTag(SECAlgorithmID **algorithmArray, SECOidTag algtag);
  354. extern const SECHashObject *
  355. NSS_CMSUtil_GetHashObjByAlgID(SECAlgorithmID *algid);
  356. extern const SEC_ASN1Template *
  357. NSS_CMSUtil_GetTemplateByTypeTag(SECOidTag type);
  358. extern size_t
  359. NSS_CMSUtil_GetSizeByTypeTag(SECOidTag type);
  360. extern NSSCMSContentInfo *
  361. NSS_CMSContent_GetContentInfo(void *msg, SECOidTag type);
  362. extern const char *
  363. NSS_CMSUtil_VerificationStatusToString(NSSCMSVerificationStatus vs);
  364. /************************************************************************
  365. * cmssigdata.c - CMS signedData methods
  366. ************************************************************************/
  367. extern NSSCMSSignedData *
  368. NSS_CMSSignedData_Create(NSSCMSMessage *cmsg);
  369. extern void
  370. NSS_CMSSignedData_Destroy(NSSCMSSignedData *sigd);
  371. /*
  372. * NSS_CMSSignedData_Encode_BeforeStart - do all the necessary things to a SignedData
  373. * before start of encoding.
  374. *
  375. * In detail:
  376. * - find out about the right value to put into sigd->version
  377. * - come up with a list of digestAlgorithms (which should be the union of the algorithms
  378. * in the signerinfos).
  379. * If we happen to have a pre-set list of algorithms (and digest values!), we
  380. * check if we have all the signerinfos' algorithms. If not, this is an error.
  381. */
  382. extern SECStatus
  383. NSS_CMSSignedData_Encode_BeforeStart(NSSCMSSignedData *sigd);
  384. extern SECStatus
  385. NSS_CMSSignedData_Encode_BeforeData(NSSCMSSignedData *sigd);
  386. /*
  387. * NSS_CMSSignedData_Encode_AfterData - do all the necessary things to a SignedData
  388. * after all the encapsulated data was passed through the encoder.
  389. *
  390. * In detail:
  391. * - create the signatures in all the SignerInfos
  392. *
  393. * Please note that nothing is done to the Certificates and CRLs in the message - this
  394. * is entirely the responsibility of our callers.
  395. */
  396. extern SECStatus
  397. NSS_CMSSignedData_Encode_AfterData(NSSCMSSignedData *sigd);
  398. extern SECStatus
  399. NSS_CMSSignedData_Decode_BeforeData(NSSCMSSignedData *sigd);
  400. /*
  401. * NSS_CMSSignedData_Decode_AfterData - do all the necessary things to a SignedData
  402. * after all the encapsulated data was passed through the decoder.
  403. */
  404. extern SECStatus
  405. NSS_CMSSignedData_Decode_AfterData(NSSCMSSignedData *sigd);
  406. /*
  407. * NSS_CMSSignedData_Decode_AfterEnd - do all the necessary things to a SignedData
  408. * after all decoding is finished.
  409. */
  410. extern SECStatus
  411. NSS_CMSSignedData_Decode_AfterEnd(NSSCMSSignedData *sigd);
  412. /*
  413. * NSS_CMSSignedData_GetSignerInfos - retrieve the SignedData's signer list
  414. */
  415. extern NSSCMSSignerInfo **
  416. NSS_CMSSignedData_GetSignerInfos(NSSCMSSignedData *sigd);
  417. extern int
  418. NSS_CMSSignedData_SignerInfoCount(NSSCMSSignedData *sigd);
  419. extern NSSCMSSignerInfo *
  420. NSS_CMSSignedData_GetSignerInfo(NSSCMSSignedData *sigd, int i);
  421. /*
  422. * NSS_CMSSignedData_GetDigestAlgs - retrieve the SignedData's digest algorithm list
  423. */
  424. extern SECAlgorithmID **
  425. NSS_CMSSignedData_GetDigestAlgs(NSSCMSSignedData *sigd);
  426. /*
  427. * NSS_CMSSignedData_GetContentInfo - return pointer to this signedData's contentinfo
  428. */
  429. extern NSSCMSContentInfo *
  430. NSS_CMSSignedData_GetContentInfo(NSSCMSSignedData *sigd);
  431. /*
  432. * NSS_CMSSignedData_GetCertificateList - retrieve the SignedData's certificate list
  433. */
  434. extern SECItem **
  435. NSS_CMSSignedData_GetCertificateList(NSSCMSSignedData *sigd);
  436. extern SECStatus
  437. NSS_CMSSignedData_ImportCerts(NSSCMSSignedData *sigd, CERTCertDBHandle *certdb,
  438. SECCertUsage certusage, PRBool keepcerts);
  439. /*
  440. * NSS_CMSSignedData_HasDigests - see if we have digests in place
  441. */
  442. extern PRBool
  443. NSS_CMSSignedData_HasDigests(NSSCMSSignedData *sigd);
  444. /*
  445. * NSS_CMSSignedData_VerifySignerInfo - check a signature.
  446. *
  447. * The digests were either calculated during decoding (and are stored in the
  448. * signedData itself) or set after decoding using NSS_CMSSignedData_SetDigests.
  449. *
  450. * The verification checks if the signing cert is valid and has a trusted chain
  451. * for the purpose specified by "certusage".
  452. */
  453. extern SECStatus
  454. NSS_CMSSignedData_VerifySignerInfo(NSSCMSSignedData *sigd, int i, CERTCertDBHandle *certdb,
  455. SECCertUsage certusage);
  456. /*
  457. * NSS_CMSSignedData_VerifyCertsOnly - verify the certs in a certs-only message
  458. */
  459. extern SECStatus
  460. NSS_CMSSignedData_VerifyCertsOnly(NSSCMSSignedData *sigd,
  461. CERTCertDBHandle *certdb,
  462. SECCertUsage usage);
  463. extern SECStatus
  464. NSS_CMSSignedData_AddCertList(NSSCMSSignedData *sigd, CERTCertificateList *certlist);
  465. /*
  466. * NSS_CMSSignedData_AddCertChain - add cert and its entire chain to the set of certs
  467. */
  468. extern SECStatus
  469. NSS_CMSSignedData_AddCertChain(NSSCMSSignedData *sigd, CERTCertificate *cert);
  470. extern SECStatus
  471. NSS_CMSSignedData_AddCertificate(NSSCMSSignedData *sigd, CERTCertificate *cert);
  472. extern PRBool
  473. NSS_CMSSignedData_ContainsCertsOrCrls(NSSCMSSignedData *sigd);
  474. extern SECStatus
  475. NSS_CMSSignedData_AddSignerInfo(NSSCMSSignedData *sigd,
  476. NSSCMSSignerInfo *signerinfo);
  477. extern SECStatus
  478. NSS_CMSSignedData_SetDigests(NSSCMSSignedData *sigd,
  479. SECAlgorithmID **digestalgs,
  480. SECItem **digests);
  481. extern SECStatus
  482. NSS_CMSSignedData_SetDigestValue(NSSCMSSignedData *sigd,
  483. SECOidTag digestalgtag,
  484. SECItem *digestdata);
  485. extern SECStatus
  486. NSS_CMSSignedData_AddDigest(PRArenaPool *poolp,
  487. NSSCMSSignedData *sigd,
  488. SECOidTag digestalgtag,
  489. SECItem *digest);
  490. extern SECItem *
  491. NSS_CMSSignedData_GetDigestValue(NSSCMSSignedData *sigd, SECOidTag digestalgtag);
  492. /*
  493. * NSS_CMSSignedData_CreateCertsOnly - create a certs-only SignedData.
  494. *
  495. * cert - base certificates that will be included
  496. * include_chain - if true, include the complete cert chain for cert
  497. *
  498. * More certs and chains can be added via AddCertificate and AddCertChain.
  499. *
  500. * An error results in a return value of NULL and an error set.
  501. */
  502. extern NSSCMSSignedData *
  503. NSS_CMSSignedData_CreateCertsOnly(NSSCMSMessage *cmsg, CERTCertificate *cert, PRBool include_chain);
  504. /************************************************************************
  505. * cmssiginfo.c - signerinfo methods
  506. ************************************************************************/
  507. extern NSSCMSSignerInfo *
  508. NSS_CMSSignerInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert, SECOidTag digestalgtag);
  509. extern NSSCMSSignerInfo *
  510. NSS_CMSSignerInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg, SECItem *subjKeyID, SECKEYPublicKey *pubKey, SECKEYPrivateKey *signingKey, SECOidTag digestalgtag);
  511. /*
  512. * NSS_CMSSignerInfo_Destroy - destroy a SignerInfo data structure
  513. */
  514. extern void
  515. NSS_CMSSignerInfo_Destroy(NSSCMSSignerInfo *si);
  516. /*
  517. * NSS_CMSSignerInfo_Sign - sign something
  518. *
  519. */
  520. extern SECStatus
  521. NSS_CMSSignerInfo_Sign(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
  522. extern SECStatus
  523. NSS_CMSSignerInfo_VerifyCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb,
  524. SECCertUsage certusage);
  525. /*
  526. * NSS_CMSSignerInfo_Verify - verify the signature of a single SignerInfo
  527. *
  528. * Just verifies the signature. The assumption is that verification of the certificate
  529. * is done already.
  530. */
  531. extern SECStatus
  532. NSS_CMSSignerInfo_Verify(NSSCMSSignerInfo *signerinfo, SECItem *digest, SECItem *contentType);
  533. extern NSSCMSVerificationStatus
  534. NSS_CMSSignerInfo_GetVerificationStatus(NSSCMSSignerInfo *signerinfo);
  535. extern SECOidData *
  536. NSS_CMSSignerInfo_GetDigestAlg(NSSCMSSignerInfo *signerinfo);
  537. extern SECOidTag
  538. NSS_CMSSignerInfo_GetDigestAlgTag(NSSCMSSignerInfo *signerinfo);
  539. extern int
  540. NSS_CMSSignerInfo_GetVersion(NSSCMSSignerInfo *signerinfo);
  541. extern CERTCertificateList *
  542. NSS_CMSSignerInfo_GetCertList(NSSCMSSignerInfo *signerinfo);
  543. /*
  544. * NSS_CMSSignerInfo_GetSigningTime - return the signing time,
  545. * in UTCTime format, of a CMS signerInfo.
  546. *
  547. * sinfo - signerInfo data for this signer
  548. *
  549. * Returns a pointer to XXXX (what?)
  550. * A return value of NULL is an error.
  551. */
  552. extern SECStatus
  553. NSS_CMSSignerInfo_GetSigningTime(NSSCMSSignerInfo *sinfo, PRTime *stime);
  554. /*
  555. * Return the signing cert of a CMS signerInfo.
  556. *
  557. * the certs in the enclosing SignedData must have been imported already
  558. */
  559. extern CERTCertificate *
  560. NSS_CMSSignerInfo_GetSigningCertificate(NSSCMSSignerInfo *signerinfo, CERTCertDBHandle *certdb);
  561. /*
  562. * NSS_CMSSignerInfo_GetSignerCommonName - return the common name of the signer
  563. *
  564. * sinfo - signerInfo data for this signer
  565. *
  566. * Returns a pointer to allocated memory, which must be freed with PORT_Free.
  567. * A return value of NULL is an error.
  568. */
  569. extern char *
  570. NSS_CMSSignerInfo_GetSignerCommonName(NSSCMSSignerInfo *sinfo);
  571. /*
  572. * NSS_CMSSignerInfo_GetSignerEmailAddress - return the common name of the signer
  573. *
  574. * sinfo - signerInfo data for this signer
  575. *
  576. * Returns a pointer to allocated memory, which must be freed.
  577. * A return value of NULL is an error.
  578. */
  579. extern char *
  580. NSS_CMSSignerInfo_GetSignerEmailAddress(NSSCMSSignerInfo *sinfo);
  581. /*
  582. * NSS_CMSSignerInfo_AddAuthAttr - add an attribute to the
  583. * authenticated (i.e. signed) attributes of "signerinfo".
  584. */
  585. extern SECStatus
  586. NSS_CMSSignerInfo_AddAuthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
  587. /*
  588. * NSS_CMSSignerInfo_AddUnauthAttr - add an attribute to the
  589. * unauthenticated attributes of "signerinfo".
  590. */
  591. extern SECStatus
  592. NSS_CMSSignerInfo_AddUnauthAttr(NSSCMSSignerInfo *signerinfo, NSSCMSAttribute *attr);
  593. /*
  594. * NSS_CMSSignerInfo_AddSigningTime - add the signing time to the
  595. * authenticated (i.e. signed) attributes of "signerinfo".
  596. *
  597. * This is expected to be included in outgoing signed
  598. * messages for email (S/MIME) but is likely useful in other situations.
  599. *
  600. * This should only be added once; a second call will do nothing.
  601. *
  602. * XXX This will probably just shove the current time into "signerinfo"
  603. * but it will not actually get signed until the entire item is
  604. * processed for encoding. Is this (expected to be small) delay okay?
  605. */
  606. extern SECStatus
  607. NSS_CMSSignerInfo_AddSigningTime(NSSCMSSignerInfo *signerinfo, PRTime t);
  608. /*
  609. * NSS_CMSSignerInfo_AddSMIMECaps - add a SMIMECapabilities attribute to the
  610. * authenticated (i.e. signed) attributes of "signerinfo".
  611. *
  612. * This is expected to be included in outgoing signed
  613. * messages for email (S/MIME).
  614. */
  615. extern SECStatus
  616. NSS_CMSSignerInfo_AddSMIMECaps(NSSCMSSignerInfo *signerinfo);
  617. /*
  618. * NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
  619. * authenticated (i.e. signed) attributes of "signerinfo".
  620. *
  621. * This is expected to be included in outgoing signed messages for email (S/MIME).
  622. */
  623. SECStatus
  624. NSS_CMSSignerInfo_AddSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
  625. /*
  626. * NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs - add a SMIMEEncryptionKeyPreferences attribute to the
  627. * authenticated (i.e. signed) attributes of "signerinfo", using the OID prefered by Microsoft.
  628. *
  629. * This is expected to be included in outgoing signed messages for email (S/MIME),
  630. * if compatibility with Microsoft mail clients is wanted.
  631. */
  632. SECStatus
  633. NSS_CMSSignerInfo_AddMSSMIMEEncKeyPrefs(NSSCMSSignerInfo *signerinfo, CERTCertificate *cert, CERTCertDBHandle *certdb);
  634. /*
  635. * NSS_CMSSignerInfo_AddCounterSignature - countersign a signerinfo
  636. */
  637. extern SECStatus
  638. NSS_CMSSignerInfo_AddCounterSignature(NSSCMSSignerInfo *signerinfo,
  639. SECOidTag digestalg, CERTCertificate signingcert);
  640. /*
  641. * XXXX the following needs to be done in the S/MIME layer code
  642. * after signature of a signerinfo is verified
  643. */
  644. extern SECStatus
  645. NSS_SMIMESignerInfo_SaveSMIMEProfile(NSSCMSSignerInfo *signerinfo);
  646. /*
  647. * NSS_CMSSignerInfo_IncludeCerts - set cert chain inclusion mode for this signer
  648. */
  649. extern SECStatus
  650. NSS_CMSSignerInfo_IncludeCerts(NSSCMSSignerInfo *signerinfo, NSSCMSCertChainMode cm, SECCertUsage usage);
  651. /************************************************************************
  652. * cmsenvdata.c - CMS envelopedData methods
  653. ************************************************************************/
  654. /*
  655. * NSS_CMSEnvelopedData_Create - create an enveloped data message
  656. */
  657. extern NSSCMSEnvelopedData *
  658. NSS_CMSEnvelopedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
  659. /*
  660. * NSS_CMSEnvelopedData_Destroy - destroy an enveloped data message
  661. */
  662. extern void
  663. NSS_CMSEnvelopedData_Destroy(NSSCMSEnvelopedData *edp);
  664. /*
  665. * NSS_CMSEnvelopedData_GetContentInfo - return pointer to this envelopedData's contentinfo
  666. */
  667. extern NSSCMSContentInfo *
  668. NSS_CMSEnvelopedData_GetContentInfo(NSSCMSEnvelopedData *envd);
  669. /*
  670. * NSS_CMSEnvelopedData_AddRecipient - add a recipientinfo to the enveloped data msg
  671. *
  672. * rip must be created on the same pool as edp - this is not enforced, though.
  673. */
  674. extern SECStatus
  675. NSS_CMSEnvelopedData_AddRecipient(NSSCMSEnvelopedData *edp, NSSCMSRecipientInfo *rip);
  676. /*
  677. * NSS_CMSEnvelopedData_Encode_BeforeStart - prepare this envelopedData for encoding
  678. *
  679. * at this point, we need
  680. * - recipientinfos set up with recipient's certificates
  681. * - a content encryption algorithm (if none, 3DES will be used)
  682. *
  683. * this function will generate a random content encryption key (aka bulk key),
  684. * initialize the recipientinfos with certificate identification and wrap the bulk key
  685. * using the proper algorithm for every certificiate.
  686. * it will finally set the bulk algorithm and key so that the encode step can find it.
  687. */
  688. extern SECStatus
  689. NSS_CMSEnvelopedData_Encode_BeforeStart(NSSCMSEnvelopedData *envd);
  690. /*
  691. * NSS_CMSEnvelopedData_Encode_BeforeData - set up encryption
  692. */
  693. extern SECStatus
  694. NSS_CMSEnvelopedData_Encode_BeforeData(NSSCMSEnvelopedData *envd);
  695. /*
  696. * NSS_CMSEnvelopedData_Encode_AfterData - finalize this envelopedData for encoding
  697. */
  698. extern SECStatus
  699. NSS_CMSEnvelopedData_Encode_AfterData(NSSCMSEnvelopedData *envd);
  700. /*
  701. * NSS_CMSEnvelopedData_Decode_BeforeData - find our recipientinfo,
  702. * derive bulk key & set up our contentinfo
  703. */
  704. extern SECStatus
  705. NSS_CMSEnvelopedData_Decode_BeforeData(NSSCMSEnvelopedData *envd);
  706. /*
  707. * NSS_CMSEnvelopedData_Decode_AfterData - finish decrypting this envelopedData's content
  708. */
  709. extern SECStatus
  710. NSS_CMSEnvelopedData_Decode_AfterData(NSSCMSEnvelopedData *envd);
  711. /*
  712. * NSS_CMSEnvelopedData_Decode_AfterEnd - finish decoding this envelopedData
  713. */
  714. extern SECStatus
  715. NSS_CMSEnvelopedData_Decode_AfterEnd(NSSCMSEnvelopedData *envd);
  716. /************************************************************************
  717. * cmsrecinfo.c - CMS recipientInfo methods
  718. ************************************************************************/
  719. /*
  720. * NSS_CMSRecipientInfo_Create - create a recipientinfo
  721. *
  722. * we currently do not create KeyAgreement recipientinfos with multiple recipientEncryptedKeys
  723. * the certificate is supposed to have been verified by the caller
  724. */
  725. extern NSSCMSRecipientInfo *
  726. NSS_CMSRecipientInfo_Create(NSSCMSMessage *cmsg, CERTCertificate *cert);
  727. extern NSSCMSRecipientInfo *
  728. NSS_CMSRecipientInfo_CreateWithSubjKeyID(NSSCMSMessage *cmsg,
  729. SECItem *subjKeyID,
  730. SECKEYPublicKey *pubKey);
  731. extern NSSCMSRecipientInfo *
  732. NSS_CMSRecipientInfo_CreateWithSubjKeyIDFromCert(NSSCMSMessage *cmsg,
  733. CERTCertificate *cert);
  734. /*
  735. * NSS_CMSRecipientInfo_CreateNew - create a blank recipientinfo for
  736. * applications which want to encode their own CMS structures and
  737. * key exchange types.
  738. */
  739. extern NSSCMSRecipientInfo *
  740. NSS_CMSRecipientInfo_CreateNew(void* pwfn_arg);
  741. /*
  742. * NSS_CMSRecipientInfo_CreateFromDER - create a recipientinfo from partially
  743. * decoded DER data for applications which want to encode their own CMS
  744. * structures and key exchange types.
  745. */
  746. extern NSSCMSRecipientInfo *
  747. NSS_CMSRecipientInfo_CreateFromDER(SECItem* input, void* pwfn_arg);
  748. extern void
  749. NSS_CMSRecipientInfo_Destroy(NSSCMSRecipientInfo *ri);
  750. /*
  751. * NSS_CMSRecipientInfo_GetCertAndKey - retrieve the cert and key from the
  752. * recipientInfo struct. If retcert or retkey are NULL, the cert or
  753. * key (respectively) would not be returned). This function is a no-op if both
  754. * retcert and retkey are NULL. Caller inherits ownership of the cert and key
  755. * he requested (and is responsible to free them).
  756. */
  757. SECStatus NSS_CMSRecipientInfo_GetCertAndKey(NSSCMSRecipientInfo *ri,
  758. CERTCertificate** retcert, SECKEYPrivateKey** retkey);
  759. extern int
  760. NSS_CMSRecipientInfo_GetVersion(NSSCMSRecipientInfo *ri);
  761. extern SECItem *
  762. NSS_CMSRecipientInfo_GetEncryptedKey(NSSCMSRecipientInfo *ri, int subIndex);
  763. /*
  764. * NSS_CMSRecipientInfo_Encode - encode an NSS_CMSRecipientInfo as ASN.1
  765. */
  766. SECStatus NSS_CMSRecipientInfo_Encode(PRArenaPool* poolp,
  767. const NSSCMSRecipientInfo *src,
  768. SECItem* returned);
  769. extern SECOidTag
  770. NSS_CMSRecipientInfo_GetKeyEncryptionAlgorithmTag(NSSCMSRecipientInfo *ri);
  771. extern SECStatus
  772. NSS_CMSRecipientInfo_WrapBulkKey(NSSCMSRecipientInfo *ri, PK11SymKey *bulkkey, SECOidTag bulkalgtag);
  773. extern PK11SymKey *
  774. NSS_CMSRecipientInfo_UnwrapBulkKey(NSSCMSRecipientInfo *ri, int subIndex,
  775. CERTCertificate *cert, SECKEYPrivateKey *privkey, SECOidTag bulkalgtag);
  776. /************************************************************************
  777. * cmsencdata.c - CMS encryptedData methods
  778. ************************************************************************/
  779. /*
  780. * NSS_CMSEncryptedData_Create - create an empty encryptedData object.
  781. *
  782. * "algorithm" specifies the bulk encryption algorithm to use.
  783. * "keysize" is the key size.
  784. *
  785. * An error results in a return value of NULL and an error set.
  786. * (Retrieve specific errors via PORT_GetError()/XP_GetError().)
  787. */
  788. extern NSSCMSEncryptedData *
  789. NSS_CMSEncryptedData_Create(NSSCMSMessage *cmsg, SECOidTag algorithm, int keysize);
  790. /*
  791. * NSS_CMSEncryptedData_Destroy - destroy an encryptedData object
  792. */
  793. extern void
  794. NSS_CMSEncryptedData_Destroy(NSSCMSEncryptedData *encd);
  795. /*
  796. * NSS_CMSEncryptedData_GetContentInfo - return pointer to encryptedData object's contentInfo
  797. */
  798. extern NSSCMSContentInfo *
  799. NSS_CMSEncryptedData_GetContentInfo(NSSCMSEncryptedData *encd);
  800. /*
  801. * NSS_CMSEncryptedData_Encode_BeforeStart - do all the necessary things to a EncryptedData
  802. * before encoding begins.
  803. *
  804. * In particular:
  805. * - set the correct version value.
  806. * - get the encryption key
  807. */
  808. extern SECStatus
  809. NSS_CMSEncryptedData_Encode_BeforeStart(NSSCMSEncryptedData *encd);
  810. /*
  811. * NSS_CMSEncryptedData_Encode_BeforeData - set up encryption
  812. */
  813. extern SECStatus
  814. NSS_CMSEncryptedData_Encode_BeforeData(NSSCMSEncryptedData *encd);
  815. /*
  816. * NSS_CMSEncryptedData_Encode_AfterData - finalize this encryptedData for encoding
  817. */
  818. extern SECStatus
  819. NSS_CMSEncryptedData_Encode_AfterData(NSSCMSEncryptedData *encd);
  820. /*
  821. * NSS_CMSEncryptedData_Decode_BeforeData - find bulk key & set up decryption
  822. */
  823. extern SECStatus
  824. NSS_CMSEncryptedData_Decode_BeforeData(NSSCMSEncryptedData *encd);
  825. /*
  826. * NSS_CMSEncryptedData_Decode_AfterData - finish decrypting this encryptedData's content
  827. */
  828. extern SECStatus
  829. NSS_CMSEncryptedData_Decode_AfterData(NSSCMSEncryptedData *encd);
  830. /*
  831. * NSS_CMSEncryptedData_Decode_AfterEnd - finish decoding this encryptedData
  832. */
  833. extern SECStatus
  834. NSS_CMSEncryptedData_Decode_AfterEnd(NSSCMSEncryptedData *encd);
  835. /************************************************************************
  836. * cmsdigdata.c - CMS encryptedData methods
  837. ************************************************************************/
  838. /*
  839. * NSS_CMSDigestedData_Create - create a digestedData object (presumably for encoding)
  840. *
  841. * version will be set by NSS_CMSDigestedData_Encode_BeforeStart
  842. * digestAlg is passed as parameter
  843. * contentInfo must be filled by the user
  844. * digest will be calculated while encoding
  845. */
  846. extern NSSCMSDigestedData *
  847. NSS_CMSDigestedData_Create(NSSCMSMessage *cmsg, SECAlgorithmID *digestalg);
  848. /*
  849. * NSS_CMSDigestedData_Destroy - destroy a digestedData object
  850. */
  851. extern void
  852. NSS_CMSDigestedData_Destroy(NSSCMSDigestedData *digd);
  853. /*
  854. * NSS_CMSDigestedData_GetContentInfo - return pointer to digestedData object's contentInfo
  855. */
  856. extern NSSCMSContentInfo *
  857. NSS_CMSDigestedData_GetContentInfo(NSSCMSDigestedData *digd);
  858. /*
  859. * NSS_CMSDigestedData_Encode_BeforeStart - do all the necessary things to a DigestedData
  860. * before encoding begins.
  861. *
  862. * In particular:
  863. * - set the right version number. The contentInfo's content type must be set up already.
  864. */
  865. extern SECStatus
  866. NSS_CMSDigestedData_Encode_BeforeStart(NSSCMSDigestedData *digd);
  867. /*
  868. * NSS_CMSDigestedData_Encode_BeforeData - do all the necessary things to a DigestedData
  869. * before the encapsulated data is passed through the encoder.
  870. *
  871. * In detail:
  872. * - set up the digests if necessary
  873. */
  874. extern SECStatus
  875. NSS_CMSDigestedData_Encode_BeforeData(NSSCMSDigestedData *digd);
  876. /*
  877. * NSS_CMSDigestedData_Encode_AfterData - do all the necessary things to a DigestedData
  878. * after all the encapsulated data was passed through the encoder.
  879. *
  880. * In detail:
  881. * - finish the digests
  882. */
  883. extern SECStatus
  884. NSS_CMSDigestedData_Encode_AfterData(NSSCMSDigestedData *digd);
  885. /*
  886. * NSS_CMSDigestedData_Decode_BeforeData - do all the necessary things to a DigestedData
  887. * before the encapsulated data is passed through the encoder.
  888. *
  889. * In detail:
  890. * - set up the digests if necessary
  891. */
  892. extern SECStatus
  893. NSS_CMSDigestedData_Decode_BeforeData(NSSCMSDigestedData *digd);
  894. /*
  895. * NSS_CMSDigestedData_Decode_AfterData - do all the necessary things to a DigestedData
  896. * after all the encapsulated data was passed through the encoder.
  897. *
  898. * In detail:
  899. * - finish the digests
  900. */
  901. extern SECStatus
  902. NSS_CMSDigestedData_Decode_AfterData(NSSCMSDigestedData *digd);
  903. /*
  904. * NSS_CMSDigestedData_Decode_AfterEnd - finalize a digestedData.
  905. *
  906. * In detail:
  907. * - check the digests for equality
  908. */
  909. extern SECStatus
  910. NSS_CMSDigestedData_Decode_AfterEnd(NSSCMSDigestedData *digd);
  911. /************************************************************************
  912. * cmsdigest.c - digestion routines
  913. ************************************************************************/
  914. /*
  915. * NSS_CMSDigestContext_StartMultiple - start digest calculation using all the
  916. * digest algorithms in "digestalgs" in parallel.
  917. */
  918. extern NSSCMSDigestContext *
  919. NSS_CMSDigestContext_StartMultiple(SECAlgorithmID **digestalgs);
  920. /*
  921. * NSS_CMSDigestContext_StartSingle - same as NSS_CMSDigestContext_StartMultiple, but
  922. * only one algorithm.
  923. */
  924. extern NSSCMSDigestContext *
  925. NSS_CMSDigestContext_StartSingle(SECAlgorithmID *digestalg);
  926. /*
  927. * NSS_CMSDigestContext_Update - feed more data into the digest machine
  928. */
  929. extern void
  930. NSS_CMSDigestContext_Update(NSSCMSDigestContext *cmsdigcx, const unsigned char *data, int len);
  931. /*
  932. * NSS_CMSDigestContext_Cancel - cancel digesting operation
  933. */
  934. extern void
  935. NSS_CMSDigestContext_Cancel(NSSCMSDigestContext *cmsdigcx);
  936. /*
  937. * NSS_CMSDigestContext_FinishMultiple - finish the digests and put them
  938. * into an array of SECItems (allocated on poolp)
  939. */
  940. extern SECStatus
  941. NSS_CMSDigestContext_FinishMultiple(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
  942. SECItem ***digestsp);
  943. /*
  944. * NSS_CMSDigestContext_FinishSingle - same as NSS_CMSDigestContext_FinishMultiple,
  945. * but for one digest.
  946. */
  947. extern SECStatus
  948. NSS_CMSDigestContext_FinishSingle(NSSCMSDigestContext *cmsdigcx, PLArenaPool *poolp,
  949. SECItem *digest);
  950. /************************************************************************
  951. *
  952. ************************************************************************/
  953. /* shortcuts for basic use */
  954. /*
  955. * NSS_CMSDEREncode - DER Encode a CMS message, with input being
  956. * the plaintext message and derOut being the output,
  957. * stored in arena's pool.
  958. */
  959. extern SECStatus
  960. NSS_CMSDEREncode(NSSCMSMessage *cmsg, SECItem *input, SECItem *derOut,
  961. PLArenaPool *arena);
  962. /************************************************************************/
  963. SEC_END_PROTOS
  964. #endif /* _CMS_H_ */