secure/lib/libcrypto/man/BIO_f_md.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH BIO_f_md 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 2
 195 \& #include <openssl/bio.h>
 196 \& #include <openssl/evp.h>
 197 .Ve
 198 .Vb 4
 199 \& BIO_METHOD *   BIO_f_md(void);
 200 \& int BIO_set_md(BIO *b,EVP_MD *md);
 201 \& int BIO_get_md(BIO *b,EVP_MD **mdp);
 202 \& int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
 203 .Ve
 204 .SH "DESCRIPTION"
 205 \fIBIO_f_md()\fR returns the message digest BIO method. This is a filter
 206 BIO that digests any data passed through it, it is a BIO wrapper
 207 for the digest routines \fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR
 208 and \fIEVP_DigestFinal()\fR.
 209 .PP
 210 Any data written or read through a digest BIO using \fIBIO_read()\fR and
 211 \fIBIO_write()\fR is digested.
 212 .PP
 213 \fIBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
 214 digest calculation and returns the digest value. \fIBIO_puts()\fR is
 215 not supported.
 216 .PP
 217 \fIBIO_reset()\fR reinitialises a digest BIO.
 218 .PP
 219 \fIBIO_set_md()\fR sets the message digest of BIO \fBb\fR to \fBmd\fR: this
 220 must be called to initialize a digest BIO before any data is
 221 passed through it. It is a \fIBIO_ctrl()\fR macro.
 222 .PP
 223 \fIBIO_get_md()\fR places the a pointer to the digest BIOs digest method
 224 in \fBmdp\fR, it is a \fIBIO_ctrl()\fR macro.
 225 .PP
 226 \fIBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
 227 .SH "NOTES"
 228 The context returned by \fIBIO_get_md_ctx()\fR can be used in calls
 229 to \fIEVP_DigestFinal()\fR and also the signature routines \fIEVP_SignFinal()\fR
 230 and \fIEVP_VerifyFinal()\fR.
 231 .PP
 232 The context returned by \fIBIO_get_md_ctx()\fR is an internal context
 233 structure. Changes made to this context will affect the digest
 234 BIO itself and the context pointer will become invalid when the digest
 235 BIO is freed.
 236 .PP
 237 After the digest has been retrieved from a digest BIO it must be
 238 reinitialized by calling \fIBIO_reset()\fR, or \fIBIO_set_md()\fR before any more
 239 data is passed through it.
 240 .PP
 241 If an application needs to call \fIBIO_gets()\fR or \fIBIO_puts()\fR through
 242 a chain containing digest BIOs then this can be done by prepending
 243 a buffering BIO.
 244 .SH "RETURN VALUES"
 245 \fIBIO_f_md()\fR returns the digest BIO method.
 246 .PP
 247 \fIBIO_set_md()\fR, \fIBIO_get_md()\fR and \fIBIO_md_ctx()\fR return 1 for success and
 248 0 for failure.
 249 .SH "EXAMPLES"
 250 The following example creates a BIO chain containing an SHA1 and MD5
 251 digest BIO and passes the string \*(L"Hello World\*(R" through it. Error
 252 checking has been omitted for clarity.
 253 .PP
 254 .Vb 14
 255 \& BIO *bio, *mdtmp;
 256 \& char message[] = "Hello World";
 257 \& bio = BIO_new(BIO_s_null());
 258 \& mdtmp = BIO_new(BIO_f_md());
 259 \& BIO_set_md(mdtmp, EVP_sha1());
 260 \& /* For BIO_push() we want to append the sink BIO and keep a note of
 261 \&  * the start of the chain.
 262 \&  */
 263 \& bio = BIO_push(mdtmp, bio);
 264 \& mdtmp = BIO_new(BIO_f_md());
 265 \& BIO_set_md(mdtmp, EVP_md5());
 266 \& bio = BIO_push(mdtmp, bio);
 267 \& /* Note: mdtmp can now be discarded */
 268 \& BIO_write(bio, message, strlen(message));
 269 .Ve
 270 The next example digests data by reading through a chain instead:
 271 .PP
 272 .Vb 14
 273 \& BIO *bio, *mdtmp;
 274 \& char buf[1024];
 275 \& int rdlen;
 276 \& bio = BIO_new_file(file, "rb");
 277 \& mdtmp = BIO_new(BIO_f_md());
 278 \& BIO_set_md(mdtmp, EVP_sha1());
 279 \& bio = BIO_push(mdtmp, bio);
 280 \& mdtmp = BIO_new(BIO_f_md());
 281 \& BIO_set_md(mdtmp, EVP_md5());
 282 \& bio = BIO_push(mdtmp, bio);
 283 \& do {
 284 \&        rdlen = BIO_read(bio, buf, sizeof(buf));
 285 \&        /* Might want to do something with the data here */
 286 \& } while(rdlen > 0);
 287 .Ve
 288 This next example retrieves the message digests from a BIO chain and
 289 outputs them. This could be used with the examples above.
 290 .PP
 291 .Vb 16
 292 \& BIO *mdtmp;
 293 \& unsigned char mdbuf[EVP_MAX_MD_SIZE];
 294 \& int mdlen;
 295 \& int i;
 296 \& mdtmp = bio;   /* Assume bio has previously been set up */
 297 \& do {
 298 \&        EVP_MD *md;
 299 \&        mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
 300 \&        if(!mdtmp) break;
 301 \&        BIO_get_md(mdtmp, &md);
 302 \&        printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
 303 \&        mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
 304 \&        for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
 305 \&        printf("\en");
 306 \&        mdtmp = BIO_next(mdtmp);
 307 \& } while(mdtmp);
 308 .Ve
 309 .Vb 1
 310 \& BIO_free_all(bio);
 311 .Ve
 312 .SH "BUGS"
 313 The lack of support for \fIBIO_puts()\fR and the non standard behaviour of
 314 \fIBIO_gets()\fR could be regarded as anomalous. It could be argued that \fIBIO_gets()\fR
 315 and \fIBIO_puts()\fR should be passed to the next BIO in the chain and digest
 316 the data passed through and that digests should be retrieved using a
 317 separate \fIBIO_ctrl()\fR call.
 318 .SH "SEE ALSO"
 319 TBA
 320
 321 .rn }` ''
 322 .IX Title "BIO_f_md 3"
 323 .IX Name "BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter"
 324
 325 .IX Header "NAME"
 326
 327 .IX Header "SYNOPSIS"
 328
 329 .IX Header "DESCRIPTION"
 330
 331 .IX Header "NOTES"
 332
 333 .IX Header "RETURN VALUES"
 334
 335 .IX Header "EXAMPLES"
 336
 337 .IX Header "BUGS"
 338
 339 .IX Header "SEE ALSO"
 340