/security/nss/lib/cryptohi/cryptohi.h

http://github.com/zpao/v8monkey · C Header · 402 lines · 75 code · 34 blank · 293 comment · 0 complexity · 160635bd042cae1eed8134f812afc8fa 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.15 2010/08/12 01:15:37 wtc%google.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, const 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,
  125. const unsigned char *buf, int len,
  126. SECKEYPrivateKey *pk, SECOidTag algid);
  127. /*
  128. ** Sign a pre-digested block of data using private key encryption, encoding
  129. ** The given signature/hash algorithm.
  130. ** "result" the final signature data (memory is allocated)
  131. ** "digest" the digest to sign
  132. ** "pk" the private key to encrypt with
  133. ** "algtag" The algorithm tag to encode (need for RSA only)
  134. */
  135. extern SECStatus SGN_Digest(SECKEYPrivateKey *privKey,
  136. SECOidTag algtag, SECItem *result, SECItem *digest);
  137. /*
  138. ** DER sign a single block of data using private key encryption and the
  139. ** MD5 hashing algorithm. This routine first computes a digital signature
  140. ** using SEC_SignData, then wraps it with an CERTSignedData and then der
  141. ** encodes the result.
  142. ** "arena" is the memory arena to use to allocate data from
  143. ** "result" the final der encoded data (memory is allocated)
  144. ** "buf" the input data to sign
  145. ** "len" the amount of data to sign
  146. ** "pk" the private key to encrypt with
  147. */
  148. extern SECStatus SEC_DerSignData(PLArenaPool *arena, SECItem *result,
  149. const unsigned char *buf, int len,
  150. SECKEYPrivateKey *pk, SECOidTag algid);
  151. /*
  152. ** Destroy a signed-data object.
  153. ** "sd" the object
  154. ** "freeit" if PR_TRUE then free the object as well as its sub-objects
  155. */
  156. extern void SEC_DestroySignedData(CERTSignedData *sd, PRBool freeit);
  157. /*
  158. ** Get the signature algorithm tag number for the given key type and hash
  159. ** algorithm tag. Returns SEC_OID_UNKNOWN if key type and hash algorithm
  160. ** do not match or are not supported.
  161. */
  162. extern SECOidTag SEC_GetSignatureAlgorithmOidTag(KeyType keyType,
  163. SECOidTag hashAlgTag);
  164. /****************************************/
  165. /*
  166. ** Signature verification operations
  167. */
  168. /*
  169. ** Create a signature verification context. This version is deprecated,
  170. ** This function is deprecated. Use VFY_CreateContextDirect or
  171. ** VFY_CreateContextWithAlgorithmID instead.
  172. ** "key" the public key to verify with
  173. ** "sig" the encrypted signature data if sig is NULL then
  174. ** VFY_EndWithSignature must be called with the correct signature at
  175. ** the end of the processing.
  176. ** "sigAlg" specifies the signing algorithm to use (including the
  177. ** hash algorthim). This must match the key type.
  178. ** "wincx" void pointer to the window context
  179. */
  180. extern VFYContext *VFY_CreateContext(SECKEYPublicKey *key, SECItem *sig,
  181. SECOidTag sigAlg, void *wincx);
  182. /*
  183. ** Create a signature verification context.
  184. ** "key" the public key to verify with
  185. ** "sig" the encrypted signature data if sig is NULL then
  186. ** VFY_EndWithSignature must be called with the correct signature at
  187. ** the end of the processing.
  188. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  189. ** raw algorithm without any hash specified. This must match the key
  190. ** type.
  191. ** "hashAlg" specifies the hashing algorithm used. If the key is an
  192. ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
  193. ** the hash is selected from data in the sig.
  194. ** "hash" optional pointer to return the actual hash algorithm used.
  195. ** in practice this should always match the passed in hashAlg (the
  196. ** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
  197. ** If this value is NULL no, hash oid is returned.
  198. ** "wincx" void pointer to the window context
  199. */
  200. extern VFYContext *VFY_CreateContextDirect(const SECKEYPublicKey *key,
  201. const SECItem *sig,
  202. SECOidTag pubkAlg,
  203. SECOidTag hashAlg,
  204. SECOidTag *hash, void *wincx);
  205. /*
  206. ** Create a signature verification context from a algorithm ID.
  207. ** "key" the public key to verify with
  208. ** "sig" the encrypted signature data if sig is NULL then
  209. ** VFY_EndWithSignature must be called with the correct signature at
  210. ** the end of the processing.
  211. ** "algid" specifies the signing algorithm and parameters to use.
  212. ** This must match the key type.
  213. ** "hash" optional pointer to return the oid of the actual hash used in
  214. ** the signature. If this value is NULL no, hash oid is returned.
  215. ** "wincx" void pointer to the window context
  216. */
  217. extern VFYContext *VFY_CreateContextWithAlgorithmID(const SECKEYPublicKey *key,
  218. const SECItem *sig,
  219. const SECAlgorithmID *algid,
  220. SECOidTag *hash,
  221. void *wincx);
  222. /*
  223. ** Destroy a verification-context object.
  224. ** "cx" the context to destroy
  225. ** "freeit" if PR_TRUE then free the object as well as its sub-objects
  226. */
  227. extern void VFY_DestroyContext(VFYContext *cx, PRBool freeit);
  228. extern SECStatus VFY_Begin(VFYContext *cx);
  229. /*
  230. ** Update a verification context with more input data. The input data
  231. ** is fed to a secure hash function (depending on what was in the
  232. ** encrypted signature data).
  233. ** "cx" the context
  234. ** "input" the input data
  235. ** "inputLen" the amount of input data
  236. */
  237. extern SECStatus VFY_Update(VFYContext *cx, const unsigned char *input,
  238. unsigned int inputLen);
  239. /*
  240. ** Finish the verification process. The return value is a status which
  241. ** indicates success or failure. On success, the SECSuccess value is
  242. ** returned. Otherwise, SECFailure is returned and the error code found
  243. ** using PORT_GetError() indicates what failure occurred.
  244. ** "cx" the context
  245. */
  246. extern SECStatus VFY_End(VFYContext *cx);
  247. /*
  248. ** Finish the verification process. The return value is a status which
  249. ** indicates success or failure. On success, the SECSuccess value is
  250. ** returned. Otherwise, SECFailure is returned and the error code found
  251. ** using PORT_GetError() indicates what failure occurred. If signature is
  252. ** supplied the verification uses this signature to verify, otherwise the
  253. ** signature passed in VFY_CreateContext() is used.
  254. ** VFY_EndWithSignature(cx,NULL); is identical to VFY_End(cx);.
  255. ** "cx" the context
  256. ** "sig" the encrypted signature data
  257. */
  258. extern SECStatus VFY_EndWithSignature(VFYContext *cx, SECItem *sig);
  259. /*
  260. ** Verify the signature on a block of data for which we already have
  261. ** the digest. The signature data is an RSA private key encrypted
  262. ** block of data formatted according to PKCS#1.
  263. ** This function is deprecated. Use VFY_VerifyDigestDirect or
  264. ** VFY_VerifyDigestWithAlgorithmID instead.
  265. ** "dig" the digest
  266. ** "key" the public key to check the signature with
  267. ** "sig" the encrypted signature data
  268. ** "sigAlg" specifies the signing algorithm to use. This must match
  269. ** the key type.
  270. ** "wincx" void pointer to the window context
  271. **/
  272. extern SECStatus VFY_VerifyDigest(SECItem *dig, SECKEYPublicKey *key,
  273. SECItem *sig, SECOidTag sigAlg, void *wincx);
  274. /*
  275. ** Verify the signature on a block of data for which we already have
  276. ** the digest. The signature data is an RSA private key encrypted
  277. ** block of data formatted according to PKCS#1.
  278. ** "dig" the digest
  279. ** "key" the public key to check the signature with
  280. ** "sig" the encrypted signature data
  281. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  282. ** raw algorithm without any hash specified. This must match the key
  283. ** type.
  284. ** "hashAlg" specifies the hashing algorithm used.
  285. ** "wincx" void pointer to the window context
  286. **/
  287. extern SECStatus VFY_VerifyDigestDirect(const SECItem *dig,
  288. const SECKEYPublicKey *key,
  289. const SECItem *sig, SECOidTag pubkAlg,
  290. SECOidTag hashAlg, void *wincx);
  291. /*
  292. ** Verify the signature on a block of data for which we already have
  293. ** the digest. The signature data is an RSA private key encrypted
  294. ** block of data formatted according to PKCS#1.
  295. ** "key" the public key to verify with
  296. ** "sig" the encrypted signature data if sig is NULL then
  297. ** VFY_EndWithSignature must be called with the correct signature at
  298. ** the end of the processing.
  299. ** "algid" specifies the signing algorithm and parameters to use.
  300. ** This must match the key type.
  301. ** "hash" oid of the actual hash used to create digest. If this value is
  302. ** not set to SEC_OID_UNKNOWN, it must match the hash of the signature.
  303. ** "wincx" void pointer to the window context
  304. */
  305. extern SECStatus VFY_VerifyDigestWithAlgorithmID(const SECItem *dig,
  306. const SECKEYPublicKey *key, const SECItem *sig,
  307. const SECAlgorithmID *algid, SECOidTag hash,
  308. void *wincx);
  309. /*
  310. ** Verify the signature on a block of data. The signature data is an RSA
  311. ** private key encrypted block of data formatted according to PKCS#1.
  312. ** This function is deprecated. Use VFY_VerifyDataDirect or
  313. ** VFY_VerifyDataWithAlgorithmID instead.
  314. ** "buf" the input data
  315. ** "len" the length of the input data
  316. ** "key" the public key to check the signature with
  317. ** "sig" the encrypted signature data
  318. ** "sigAlg" specifies the signing algorithm to use. This must match
  319. ** the key type.
  320. ** "wincx" void pointer to the window context
  321. */
  322. extern SECStatus VFY_VerifyData(const unsigned char *buf, int len,
  323. const SECKEYPublicKey *key, const SECItem *sig,
  324. SECOidTag sigAlg, void *wincx);
  325. /*
  326. ** Verify the signature on a block of data. The signature data is an RSA
  327. ** private key encrypted block of data formatted according to PKCS#1.
  328. ** "buf" the input data
  329. ** "len" the length of the input data
  330. ** "key" the public key to check the signature with
  331. ** "sig" the encrypted signature data
  332. ** "pubkAlg" specifies the cryptographic signing algorithm to use (the
  333. ** raw algorithm without any hash specified. This must match the key
  334. ** type.
  335. ** "hashAlg" specifies the hashing algorithm used. If the key is an
  336. ** RSA key, and sig is not NULL, then hashAlg can be SEC_OID_UNKNOWN.
  337. ** the hash is selected from data in the sig.
  338. ** "hash" optional pointer to return the actual hash algorithm used.
  339. ** in practice this should always match the passed in hashAlg (the
  340. ** exception is the case where hashAlg is SEC_OID_UNKNOWN above).
  341. ** If this value is NULL no, hash oid is returned.
  342. ** "wincx" void pointer to the window context
  343. */
  344. extern SECStatus VFY_VerifyDataDirect(const unsigned char *buf, int len,
  345. const SECKEYPublicKey *key,
  346. const SECItem *sig,
  347. SECOidTag pubkAlg, SECOidTag hashAlg,
  348. SECOidTag *hash, void *wincx);
  349. /*
  350. ** Verify the signature on a block of data. The signature data is an RSA
  351. ** private key encrypted block of data formatted according to PKCS#1.
  352. ** "buf" the input data
  353. ** "len" the length of the input data
  354. ** "key" the public key to check the signature with
  355. ** "sig" the encrypted signature data
  356. ** "algid" specifies the signing algorithm and parameters to use.
  357. ** This must match the key type.
  358. ** "hash" optional pointer to return the oid of the actual hash used in
  359. ** the signature. If this value is NULL no, hash oid is returned.
  360. ** "wincx" void pointer to the window context
  361. */
  362. extern SECStatus VFY_VerifyDataWithAlgorithmID(const unsigned char *buf,
  363. int len, const SECKEYPublicKey *key,
  364. const SECItem *sig,
  365. const SECAlgorithmID *algid, SECOidTag *hash,
  366. void *wincx);
  367. SEC_END_PROTOS
  368. #endif /* _CRYPTOHI_H_ */