sechash 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164
  1. .TH SECHASH 2
  2. .SH NAME
  3. md4, md5, sha1, aes, hmac_x, hmac_md5, hmac_sha1, hmac_aes, md5pickle, md5unpickle, sha1pickle, sha1unpickle \- cryptographically secure hashes
  4. .SH SYNOPSIS
  5. .de Ti
  6. .in +0.5i
  7. .ti -0.5i
  8. ..
  9. .B #include <u.h>
  10. .br
  11. .B #include <libc.h>
  12. .br
  13. .B #include <mp.h>
  14. .br
  15. .B #include <libsec.h>
  16. .PP
  17. .Ti
  18. .B
  19. DigestState* md4(uchar *data, ulong dlen, uchar *digest, DigestState *state)
  20. .PP
  21. .Ti
  22. .B
  23. DigestState* md5(uchar *data, ulong dlen, uchar *digest, DigestState *state)
  24. .PP
  25. .B
  26. char* md5pickle(MD5state *state)
  27. .PP
  28. .B
  29. MD5state* md5unpickle(char *p);
  30. .PP
  31. .Ti
  32. .B
  33. DigestState* sha1(uchar *data, ulong dlen, uchar *digest, DigestState *state)
  34. .PP
  35. .B
  36. char* sha1pickle(MD5state *state)
  37. .PP
  38. .B
  39. MD5state* sha1unpickle(char *p);
  40. .PP
  41. .Ti
  42. .B
  43. DigestState* aes(uchar *data, ulong dlen, uchar *digest, DigestState *state)
  44. .PP
  45. .Ti
  46. .B
  47. DigestState* hmac_x(uchar *p, ulong len, uchar *key, ulong klen, uchar *digest, DigestState *s, DigestState*(*x)(uchar*, ulong, uchar*, DigestState*), int xlen)
  48. .PP
  49. .Ti
  50. .B
  51. DigestState* hmac_md5(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DigestState *state)
  52. .PP
  53. .Ti
  54. .B
  55. DigestState* hmac_sha1(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DigestState *state)
  56. .PP
  57. .Ti
  58. .B
  59. DigestState* hmac_aes(uchar *data, ulong dlen, uchar *key, ulong klen, uchar *digest, DigestState *state)
  60. .SH DESCRIPTION
  61. We support several secure hash functions. The output of a
  62. hash is called a
  63. .IR digest .
  64. A hash is secure if, given the hashed data and the digest,
  65. it is difficult to predict the change to the digest resulting
  66. from some change to the data without rehashing
  67. the whole data. Therefore, if a secret is part of the hashed
  68. data, the digest can be used as an integrity check of the data by anyone
  69. possessing the secret.
  70. .PP
  71. The routines
  72. .IR md4 ,
  73. .IR md5 ,
  74. .IR sha1 ,
  75. .IR aes ,
  76. .IR hmac_md5 ,
  77. .IR hmac_sha1 ,
  78. and
  79. .I hmac_aes
  80. differ only in the length of the resulting digest
  81. and in the security of the hash. Usage for each is the same.
  82. The first call to the routine should have
  83. .B nil
  84. as the
  85. .I state
  86. parameter. This call returns a state which can be used to chain
  87. subsequent calls.
  88. The last call should have digest
  89. .RL non- nil .
  90. .I Digest
  91. must point to a buffer of at least the size of the digest produced.
  92. This last call will free the state and copy the result into
  93. .IR digest .
  94. .PP
  95. The constants
  96. .IR MD4dlen ,
  97. .IR MD5dlen ,
  98. .IR SHA1dlen ,
  99. and
  100. .I AESdlen
  101. define the lengths of the digests.
  102. .PP
  103. .IR Hmac_md5 ,
  104. .IR hmac_sha1 .
  105. and
  106. .I hmac_aes
  107. are used slightly differently. These hash algorithms are keyed and require
  108. a key to be specified on every call.
  109. The digest lengths for these hashes are
  110. .IR MD5dlen ,
  111. .IR SHA1dlen ,
  112. and
  113. .I AESdlen
  114. respectively.
  115. These routines all call
  116. .I hmac_x
  117. internally, but
  118. .I hmac_x
  119. is not intended for general use.
  120. .PP
  121. The functions
  122. .I md5pickle
  123. and
  124. .I sha1pickle
  125. marshal the state of a digest for transmission.
  126. .I Md5unpickle
  127. and
  128. .I sha1unpickle
  129. unmarshal a pickled digest.
  130. All four routines return a pointer to a newly
  131. .IR malloc (2)'d
  132. object.
  133. .SH EXAMPLES
  134. To hash a single buffer using
  135. .IR md5 :
  136. .IP
  137. .EX
  138. uchar digest[MD5dlen];
  139. md5(data, len, digest, nil);
  140. .EE
  141. .PP
  142. To chain a number of buffers together,
  143. bounded on each end by some secret:
  144. .IP
  145. .EX
  146. char buf[256];
  147. uchar digest[MD5dlen];
  148. DigestState *s;
  149. s = md5("my password", 11, nil, nil);
  150. while((n = read(fd, buf, 256)) > 0)
  151. md5(buf, n, nil, s);
  152. md5("drowssap ym", 11, digest, s);
  153. .EE
  154. .SH SOURCE
  155. .B /sys/src/libsec
  156. .SH SEE ALSO
  157. .IR aes (2),
  158. .IR blowfish (2),
  159. .IR des (2),
  160. .IR elgamal (2),
  161. .IR rc4 (2),
  162. .IR rsa (2)