secure/lib/libcrypto/man/BIO_f_md.3

   1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "BIO_f_md 3"
 136 .TH BIO_f_md 3 "2015-12-03" "1.0.1q" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx \- message digest BIO filter
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 2
 146 \& #include <openssl/bio.h>
 147 \& #include <openssl/evp.h>
 148 \&
 149 \& BIO_METHOD *   BIO_f_md(void);
 150 \& int BIO_set_md(BIO *b,EVP_MD *md);
 151 \& int BIO_get_md(BIO *b,EVP_MD **mdp);
 152 \& int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\fIBIO_f_md()\fR returns the message digest \s-1BIO\s0 method. This is a filter
 157 \&\s-1BIO\s0 that digests any data passed through it, it is a \s-1BIO\s0 wrapper
 158 for the digest routines \fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR
 159 and \fIEVP_DigestFinal()\fR.
 160 .PP
 161 Any data written or read through a digest \s-1BIO\s0 using \fIBIO_read()\fR and
 162 \&\fIBIO_write()\fR is digested.
 163 .PP
 164 \&\fIBIO_gets()\fR, if its \fBsize\fR parameter is large enough finishes the
 165 digest calculation and returns the digest value. \fIBIO_puts()\fR is
 166 not supported.
 167 .PP
 168 \&\fIBIO_reset()\fR reinitialises a digest \s-1BIO.\s0
 169 .PP
 170 \&\fIBIO_set_md()\fR sets the message digest of \s-1BIO \s0\fBb\fR to \fBmd\fR: this
 171 must be called to initialize a digest \s-1BIO\s0 before any data is
 172 passed through it. It is a \fIBIO_ctrl()\fR macro.
 173 .PP
 174 \&\fIBIO_get_md()\fR places the a pointer to the digest BIOs digest method
 175 in \fBmdp\fR, it is a \fIBIO_ctrl()\fR macro.
 176 .PP
 177 \&\fIBIO_get_md_ctx()\fR returns the digest BIOs context into \fBmdcp\fR.
 178 .SH "NOTES"
 179 .IX Header "NOTES"
 180 The context returned by \fIBIO_get_md_ctx()\fR can be used in calls
 181 to \fIEVP_DigestFinal()\fR and also the signature routines \fIEVP_SignFinal()\fR
 182 and \fIEVP_VerifyFinal()\fR.
 183 .PP
 184 The context returned by \fIBIO_get_md_ctx()\fR is an internal context
 185 structure. Changes made to this context will affect the digest
 186 \&\s-1BIO\s0 itself and the context pointer will become invalid when the digest
 187 \&\s-1BIO\s0 is freed.
 188 .PP
 189 After the digest has been retrieved from a digest \s-1BIO\s0 it must be
 190 reinitialized by calling \fIBIO_reset()\fR, or \fIBIO_set_md()\fR before any more
 191 data is passed through it.
 192 .PP
 193 If an application needs to call \fIBIO_gets()\fR or \fIBIO_puts()\fR through
 194 a chain containing digest BIOs then this can be done by prepending
 195 a buffering \s-1BIO.\s0
 196 .PP
 197 Before OpenSSL 1.0.0 the call to \fIBIO_get_md_ctx()\fR would only work if the \s-1BIO\s0
 198 had been initialized for example by calling \fIBIO_set_md()\fR ). In OpenSSL
 199 1.0.0 and later the context is always returned and the \s-1BIO\s0 is state is set
 200 to initialized. This allows applications to initialize the context externally
 201 if the standard calls such as \fIBIO_set_md()\fR are not sufficiently flexible.
 202 .SH "RETURN VALUES"
 203 .IX Header "RETURN VALUES"
 204 \&\fIBIO_f_md()\fR returns the digest \s-1BIO\s0 method.
 205 .PP
 206 \&\fIBIO_set_md()\fR, \fIBIO_get_md()\fR and \fIBIO_md_ctx()\fR return 1 for success and
 207 0 for failure.
 208 .SH "EXAMPLES"
 209 .IX Header "EXAMPLES"
 210 The following example creates a \s-1BIO\s0 chain containing an \s-1SHA1\s0 and \s-1MD5\s0
 211 digest \s-1BIO\s0 and passes the string \*(L"Hello World\*(R" through it. Error
 212 checking has been omitted for clarity.
 213 .PP
 214 .Vb 10
 215 \& BIO *bio, *mdtmp;
 216 \& char message[] = "Hello World";
 217 \& bio = BIO_new(BIO_s_null());
 218 \& mdtmp = BIO_new(BIO_f_md());
 219 \& BIO_set_md(mdtmp, EVP_sha1());
 220 \& /* For BIO_push() we want to append the sink BIO and keep a note of
 221 \&  * the start of the chain.
 222 \&  */
 223 \& bio = BIO_push(mdtmp, bio);
 224 \& mdtmp = BIO_new(BIO_f_md());
 225 \& BIO_set_md(mdtmp, EVP_md5());
 226 \& bio = BIO_push(mdtmp, bio);
 227 \& /* Note: mdtmp can now be discarded */
 228 \& BIO_write(bio, message, strlen(message));
 229 .Ve
 230 .PP
 231 The next example digests data by reading through a chain instead:
 232 .PP
 233 .Vb 10
 234 \& BIO *bio, *mdtmp;
 235 \& char buf[1024];
 236 \& int rdlen;
 237 \& bio = BIO_new_file(file, "rb");
 238 \& mdtmp = BIO_new(BIO_f_md());
 239 \& BIO_set_md(mdtmp, EVP_sha1());
 240 \& bio = BIO_push(mdtmp, bio);
 241 \& mdtmp = BIO_new(BIO_f_md());
 242 \& BIO_set_md(mdtmp, EVP_md5());
 243 \& bio = BIO_push(mdtmp, bio);
 244 \& do {
 245 \&        rdlen = BIO_read(bio, buf, sizeof(buf));
 246 \&        /* Might want to do something with the data here */
 247 \& } while(rdlen > 0);
 248 .Ve
 249 .PP
 250 This next example retrieves the message digests from a \s-1BIO\s0 chain and
 251 outputs them. This could be used with the examples above.
 252 .PP
 253 .Vb 10
 254 \& BIO *mdtmp;
 255 \& unsigned char mdbuf[EVP_MAX_MD_SIZE];
 256 \& int mdlen;
 257 \& int i;
 258 \& mdtmp = bio;   /* Assume bio has previously been set up */
 259 \& do {
 260 \&        EVP_MD *md;
 261 \&        mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
 262 \&        if(!mdtmp) break;
 263 \&        BIO_get_md(mdtmp, &md);
 264 \&        printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
 265 \&        mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
 266 \&        for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
 267 \&        printf("\en");
 268 \&        mdtmp = BIO_next(mdtmp);
 269 \& } while(mdtmp);
 270 \&
 271 \& BIO_free_all(bio);
 272 .Ve
 273 .SH "BUGS"
 274 .IX Header "BUGS"
 275 The lack of support for \fIBIO_puts()\fR and the non standard behaviour of
 276 \&\fIBIO_gets()\fR could be regarded as anomalous. It could be argued that \fIBIO_gets()\fR
 277 and \fIBIO_puts()\fR should be passed to the next \s-1BIO\s0 in the chain and digest
 278 the data passed through and that digests should be retrieved using a
 279 separate \fIBIO_ctrl()\fR call.
 280 .SH "SEE ALSO"
 281 .IX Header "SEE ALSO"
 282 \&\s-1TBA\s0