/gecko_api/include/cryptohi.h

http://firefox-mac-pdf.googlecode.com/ · C Header · 401 lines · 74 code · 34 blank · 293 comment · 0 complexity · 673e165a37a9513c8c3caa3c9756bd72 MD5 · raw file

  1. /*
  2. * crypto.h - public data structures and prototypes for the crypto library
  3. *
  4. * ***** BEGIN LICENSE BLOCK *****
  5. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  6. *
  7. * The contents of this file are subject to the Mozilla Public License Version
  8. * 1.1 (the "License"); you may not use this file except in compliance with
  9. * the License. You may obtain a copy of the License at
  10. * http://www.mozilla.org/MPL/
  11. *
  12. * Software distributed under the License is distributed on an "AS IS" basis,
  13. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14. * for the specific language governing rights and limitations under the
  15. * License.
  16. *
  17. * The Original Code is the Netscape security libraries.
  18. *
  19. * The Initial Developer of the Original Code is
  20. * Netscape Communications Corporation.
  21. * Portions created by the Initial Developer are Copyright (C) 1994-2000
  22. * the Initial Developer. All Rights Reserved.
  23. *
  24. * Contributor(s):
  25. * Dr Vipul Gupta <vipul.gupta@sun.com>, Sun Microsystems Laboratories
  26. *
  27. * Alternatively, the contents of this file may be used under the terms of
  28. * either the GNU General Public License Version 2 or later (the "GPL"), or
  29. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30. * in which case the provisions of the GPL or the LGPL are applicable instead
  31. * of those above. If you wish to allow use of your version of this file only
  32. * under the terms of either the GPL or the LGPL, and not to allow others to
  33. * use your version of this file under the terms of the MPL, indicate your
  34. * decision by deleting the provisions above and replace them with the notice
  35. * and other provisions required by the GPL or the LGPL. If you do not delete
  36. * the provisions above, a recipient may use your version of this file under
  37. * the terms of any one of the MPL, the GPL or the LGPL.
  38. *
  39. * ***** END LICENSE BLOCK ***** */
  40. /* $Id: cryptohi.h,v 1.11 2006/03/15 21:42:21 rrelyea%redhat.com Exp $ */
  41. #ifndef _CRYPTOHI_H_
  42. #define _CRYPTOHI_H_
  43. #include "blapit.h"
  44. #include "seccomon.h"
  45. #include "secoidt.h"
  46. #include "secdert.h"
  47. #include "cryptoht.h"
  48. #include "keyt.h"
  49. #include "certt.h"
  50. SEC_BEGIN_PROTOS
  51. /****************************************/
  52. /*
  53. ** DER encode/decode (EC)DSA signatures
  54. */
  55. /* ANSI X9.57 defines DSA signatures as DER encoded data. Our DSA code (and
  56. * most of the rest of the world) just generates 40 bytes of raw data. These
  57. * functions convert between formats.
  58. */
  59. extern SECStatus DSAU_EncodeDerSig(SECItem *dest, SECItem *src);
  60. extern SECItem *DSAU_DecodeDerSig(const SECItem *item);
  61. /*
  62. * Unlike DSA, raw ECDSA signatures do not have a fixed length.
  63. * Rather they contain two integers r and s whose length depends
  64. * on the size of the EC key used for signing.
  65. *
  66. * We can reuse the DSAU_EncodeDerSig interface to DER encode
  67. * raw ECDSA signature keeping in mind that the length of r
  68. * is the same as that of s and exactly half of src->len.
  69. *
  70. * For decoding, we need to pass the length of the desired
  71. * raw signature (twice the key size) explicitly.
  72. */
  73. extern SECStatus DSAU_EncodeDerSigWithLen(SECItem *dest, SECItem *src,
  74. unsigned int len);
  75. extern SECItem *DSAU_DecodeDerSigToLen(const SECItem *item, unsigned int len);
  76. /****************************************/
  77. /*
  78. ** Signature creation operations
  79. */
  80. /*
  81. ** Create a new signature context used for signing a data stream.
  82. ** "alg" the signature algorithm to use (e.g. SEC_OID_RSA_WITH_MD5)
  83. ** "privKey" the private key to use
  84. */
  85. extern SGNContext *SGN_NewContext(SECOidTag alg, SECKEYPrivateKey *privKey);
  86. /*
  87. ** Destroy a signature-context object
  88. ** "key" the object
  89. ** "freeit" if PR_TRUE then free the object as well as its sub-objects
  90. */
  91. extern void SGN_DestroyContext(SGNContext *cx, PRBool freeit);
  92. /*
  93. ** Reset the signing context "cx" to its initial state, preparing it for
  94. ** another stream of data.
  95. */
  96. extern SECStatus SGN_Begin(SGNContext *cx);
  97. /*
  98. ** Update the signing context with more data to sign.
  99. ** "cx" the context
  100. ** "input" the input data to sign
  101. ** "inputLen" the length of the input data
  102. */
  103. extern SECStatus SGN_Update(SGNContext *cx, unsigned char *input,
  104. unsigned int inputLen);
  105. /*
  106. ** Finish the signature process. Use either k0 or k1 to sign the data
  107. ** stream that was input using SGN_Update. The resulting signature is
  108. ** formatted using PKCS#1 and then encrypted using RSA private or public
  109. ** encryption.
  110. ** "cx" the context
  111. ** "result" the final signature data (memory is allocated)
  112. */
  113. extern SECStatus SGN_End(SGNContext *cx, SECItem *result);
  114. /*
  115. ** Sign a single block of data using private key encryption and given
  116. ** signature/hash algorithm.
  117. ** "result" the final signature data (memory is allocated)
  118. ** "buf" the input data to sign
  119. ** "len" the amount of data to sign
  120. ** "pk" the private key to encrypt with
  121. ** "algid" the signature/hash algorithm to sign with
  122. ** (must be compatible with the key type).
  123. */
  124. extern SECStatus SEC_SignData(SECItem *result, unsigned char *buf, int len,
  125. SECKEYPrivateKey *pk, SECOidTag algid);
  126. /*
  127. ** Sign a pre-digested block of data using private key encryption, encoding
  128. ** The given signature/hash algorithm.
  129. ** "result" the final signature data (memory is allocated)
  130. ** "digest" the digest to sign
  131. ** "pk" the private key to encrypt with
  132. ** "algtag" The algorithm tag to encode (need for RSA only)
  133. */
  134. extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
  135. SECOidTag algtag, SECItem *result, SECItem *digest);
  136. /*
  137. ** DER sign a single block of data using private key encryption and the
  138. ** MD5 hashing algorithm. This routine first computes a digital signature
  139. ** using SEC_SignData, then wraps it with an CERTSignedData and then der
  140. ** encodes the result.
  141. ** "arena" is the memory arena to use to allocate data from
  142. ** "result" the final der encoded data (memory is allocated)
  143. ** "buf" the input data to sign
  144. ** "len" the amount of data to sign
  145. ** "pk" the private key to encrypt with
  146. */
  147. extern SECStatus SEC_DerSignData(PRArenaPool *arena, SECItem *result,
  148. unsigned char *buf, int len,
  149. SECKEYPrivateKey *pk, SECOidTag algid);
  150. /*
  151. ** Destroy a signed-data object.
  152. ** "sd" the object
  153. ** "freeit" if PR_TRUE then free the object as well as its sub-objects
  154. */
  155. extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
  156. /*
  157. ** Get the signature algorithm tag number for the given key type and hash
  158. ** algorithm tag. Returns SEC_OID_UNKNOWN if key type and hash algorithm
  159. ** do not match or are not supported.
  160. */
  161. extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
  162. SECOidTag hashAlgTag);
  163. /****************************************/
  164. /*
  165. ** Signature verification operations
  166. */
  167. /*
  168. ** Create a signature verification context. This version is deprecated,
  169. ** This function is deprecated. Use VFY_CreateContextDirect or
  170. ** VFY_CreateContextWithAlgorithmID instead.
  171. ** "key" the public key to verify with
  172. ** "sig" the encrypted signature data if sig is NULL then
  173. ** VFY_EndWithSignature must be called with the correct signature at
  174. ** the end of the processing.
  175. ** "sigAlg" specifies the signing algorithm to use (including the
  176. ** hash algorthim). This must match the key type.
  177. ** "wincx" void pointer to the window context
  178. */
  179. extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
  180. SECOidTag sigAlg, void *wincx);
  181. /*
  182. ** Create a signature verification context.
  183. ** "key" the public key to verify with
  184. ** "sig" the encrypted signature data if sig is NULL then
  185. ** VFY_EndWithSignature must be called with the correct signature at
  186. ** the end of the processing.
  187. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  188. ** raw algorithm without any hash specified. This must match the key
  189. ** type.
  190. ** "hashAlg" specifies the hashing algorithm used. If the key is an
  191. ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
  192. ** the hash is selected from data in the sig.
  193. ** "hash" optional pointer to return the actual hash algorithm used.
  194. ** in practice this should always match the passed in hashAlg (the
  195. ** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
  196. ** If this value is NULL no, hash oid is returned.
  197. ** "wincx" void pointer to the window context
  198. */
  199. extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key,
  200. const SECItem *sig,
  201. SECOidTag pubkAlg,
  202. SECOidTag hashAlg,
  203. SECOidTag *hash, void *wincx);
  204. /*
  205. ** Create a signature verification context from a algorithm ID.
  206. ** "key" the public key to verify with
  207. ** "sig" the encrypted signature data if sig is NULL then
  208. ** VFY_EndWithSignature must be called with the correct signature at
  209. ** the end of the processing.
  210. ** "algid" specifies the signing algorithm and parameters to use.
  211. ** This must match the key type.
  212. ** "hash" optional pointer to return the oid of the actual hash used in
  213. ** the signature. If this value is NULL no, hash oid is returned.
  214. ** "wincx" void pointer to the window context
  215. */
  216. extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key,
  217. const SECItem *sig,
  218. const SECAlgorithmID *algid,
  219. SECOidTag *hash,
  220. void *wincx);
  221. /*
  222. ** Destroy a verification-context object.
  223. ** "cx" the context to destroy
  224. ** "freeit" if PR_TRUE then free the object as well as its sub-objects
  225. */
  226. extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
  227. extern SECStatus VFY_Begin(VFYContext *cx);
  228. /*
  229. ** Update a verification context with more input data. The input data
  230. ** is fed to a secure hash function (depending on what was in the
  231. ** encrypted signature data).
  232. ** "cx" the context
  233. ** "input" the input data
  234. ** "inputLen" the amount of input data
  235. */
  236. extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input,
  237. unsigned int inputLen);
  238. /*
  239. ** Finish the verification process. The return value is a status which
  240. ** indicates success or failure. On success, the SECSuccess value is
  241. ** returned. Otherwise, SECFailure is returned and the error code found
  242. ** using PORT_GetError() indicates what failure occurred.
  243. ** "cx" the context
  244. */
  245. extern SECStatus VFY_End(VFYContext *cx);
  246. /*
  247. ** Finish the verification process. The return value is a status which
  248. ** indicates success or failure. On success, the SECSuccess value is
  249. ** returned. Otherwise, SECFailure is returned and the error code found
  250. ** using PORT_GetError() indicates what failure occurred. If signature is
  251. ** supplied the verification uses this signature to verify, otherwise the
  252. ** signature passed in VFY_CreateContext() is used.
  253. ** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
  254. ** "cx" the context
  255. ** "sig" the encrypted signature data
  256. */
  257. extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
  258. /*
  259. ** Verify the signature on a block of data for which we already have
  260. ** the digest. The signature data is an RSA private key encrypted
  261. ** block of data formatted according to PKCS#1.
  262. ** This function is deprecated. Use VFY_VerifyDigestDirect or
  263. ** VFY_VerifyDigestWithAlgorithmID instead.
  264. ** "dig" the digest
  265. ** "key" the public key to check the signature with
  266. ** "sig" the encrypted signature data
  267. ** "sigAlg" specifies the signing algorithm to use. This must match
  268. ** the key type.
  269. ** "wincx" void pointer to the window context
  270. **/
  271. extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
  272. SECItem *sig, SECOidTag sigAlg, void *wincx);
  273. /*
  274. ** Verify the signature on a block of data for which we already have
  275. ** the digest. The signature data is an RSA private key encrypted
  276. ** block of data formatted according to PKCS#1.
  277. ** "dig" the digest
  278. ** "key" the public key to check the signature with
  279. ** "sig" the encrypted signature data
  280. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  281. ** raw algorithm without any hash specified. This must match the key
  282. ** type.
  283. ** "hashAlg" specifies the hashing algorithm used.
  284. ** "wincx" void pointer to the window context
  285. **/
  286. extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig,
  287. const SECKEYPublicKey *key,
  288. const SECItem *sig, SECOidTag pubkAlg,
  289. SECOidTag hashAlg, void *wincx);
  290. /*
  291. ** Verify the signature on a block of data for which we already have
  292. ** the digest. The signature data is an RSA private key encrypted
  293. ** block of data formatted according to PKCS#1.
  294. ** "key" the public key to verify with
  295. ** "sig" the encrypted signature data if sig is NULL then
  296. ** VFY_EndWithSignature must be called with the correct signature at
  297. ** the end of the processing.
  298. ** "algid" specifies the signing algorithm and parameters to use.
  299. ** This must match the key type.
  300. ** "hash" oid of the actual hash used to create digest. If this value is
  301. ** not set to SEC_OID_UNKNOWN, it must match the hash of the signature.
  302. ** "wincx" void pointer to the window context
  303. */
  304. extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig,
  305. const SECKEYPublicKey *key, const SECItem *sig,
  306. const SECAlgorithmID *algid, SECOidTag hash,
  307. void *wincx);
  308. /*
  309. ** Verify the signature on a block of data. The signature data is an RSA
  310. ** private key encrypted block of data formatted according to PKCS#1.
  311. ** This function is deprecated. Use VFY_VerifyDataDirect or
  312. ** VFY_VerifyDataWithAlgorithmID instead.
  313. ** "buf" the input data
  314. ** "len" the length of the input data
  315. ** "key" the public key to check the signature with
  316. ** "sig" the encrypted signature data
  317. ** "sigAlg" specifies the signing algorithm to use. This must match
  318. ** the key type.
  319. ** "wincx" void pointer to the window context
  320. */
  321. extern SECStatus VFY_VerifyData(unsigned char *buf, int len,
  322. SECKEYPublicKey *key, SECItem *sig,
  323. SECOidTag sigAlg, void *wincx);
  324. /*
  325. ** Verify the signature on a block of data. The signature data is an RSA
  326. ** private key encrypted block of data formatted according to PKCS#1.
  327. ** "buf" the input data
  328. ** "len" the length of the input data
  329. ** "key" the public key to check the signature with
  330. ** "sig" the encrypted signature data
  331. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  332. ** raw algorithm without any hash specified. This must match the key
  333. ** type.
  334. ** "hashAlg" specifies the hashing algorithm used. If the key is an
  335. ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
  336. ** the hash is selected from data in the sig.
  337. ** "hash" optional pointer to return the actual hash algorithm used.
  338. ** in practice this should always match the passed in hashAlg (the
  339. ** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
  340. ** If this value is NULL no, hash oid is returned.
  341. ** "wincx" void pointer to the window context
  342. */
  343. extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len,
  344. const SECKEYPublicKey *key,
  345. const SECItem *sig,
  346. SECOidTag pubkAlg, SECOidTag hashAlg,
  347. SECOidTag *hash, void *wincx);
  348. /*
  349. ** Verify the signature on a block of data. The signature data is an RSA
  350. ** private key encrypted block of data formatted according to PKCS#1.
  351. ** "buf" the input data
  352. ** "len" the length of the input data
  353. ** "key" the public key to check the signature with
  354. ** "sig" the encrypted signature data
  355. ** "algid" specifies the signing algorithm and parameters to use.
  356. ** This must match the key type.
  357. ** "hash" optional pointer to return the oid of the actual hash used in
  358. ** the signature. If this value is NULL no, hash oid is returned.
  359. ** "wincx" void pointer to the window context
  360. */
  361. extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf,
  362. int len, const SECKEYPublicKey *key,
  363. const SECItem *sig,
  364. const SECAlgorithmID *algid, SECOidTag *hash,
  365. void *wincx);
  366. SEC_END_PROTOS
  367. #endif /* _CRYPTOHI_H_ */