sechash 2.9 KB

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