~ubuntu-branches/ubuntu/intrepid/perl-doc-html/intrepid

<div id="breadCrumbs"><a href="index.html">Home</a> > <a href="index-modules-A.html">Core modules</a> > <a href="index-modules-D.html">D</a> > Digest</div>

<div id="contentBody"><div class="title_container"><div class="page_title">Digest</div></div><ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><li><a href="#OO-INTERFACE">OO INTERFACE</a><li><a href="#Digest-speed">Digest speed</a><li><a href="#SEE-ALSO">SEE ALSO</a><li><a href="#AUTHOR">AUTHOR</a></ul><a name="NAME"></a><h1>NAME</h1>

Digest - Modules that calculate message digests

<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>

<pre class="verbatim"> $md5 = <a class="l_w" href="Digest.html">Digest</a>->new("MD5");

$sha1 = <a class="l_w" href="Digest.html">Digest</a>->new("SHA-1");

$sha256 = <a class="l_w" href="Digest.html">Digest</a>->new("SHA-256");

$sha384 = <a class="l_w" href="Digest.html">Digest</a>->new("SHA-384");

$sha512 = <a class="l_w" href="Digest.html">Digest</a>->new("SHA-512");</pre>

<pre class="verbatim"> $hmac = <a class="l_w" href="Digest.html">Digest</a>->HMAC_MD5($key);</pre>

<pre class="verbatim"> $md5 = Digest->new("MD5");

$sha1 = Digest->new("SHA-1");

$sha256 = Digest->new("SHA-256");

$sha384 = Digest->new("SHA-384");

$sha512 = Digest->new("SHA-512");</pre>

<pre class="verbatim"> $hmac = Digest->HMAC_MD5($key);</pre>

<a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>

The <code class="inline">Digest::</code>

The <code class="inline">Digest::</code>

modules calculate digests, also called "fingerprints"

or "hashes", of some data, called a message. The digest is (usually)

100

some small/fixed size string. The actual size of the digest depend of

109

112

digest for a different message it is wise to make it easy to plug in

110

113

stronger algorithms as the one used grow weaker. Using the interface

111

114

documented here should make it easy to change algorithms later.

112

All <code class="inline">Digest::</code>

115

All <code class="inline">Digest::</code>

113

116

modules provide the same programming interface. A

114

117

functional interface for simple use, as well as an object oriented

115

118

interface that can handle messages of arbitrary length and which can

133

136

The functional interface is simply importable functions with the same

134

137

name as the algorithm. The functions take the message as argument and

135

138

return the digest. Example:

136

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> <a class="l_w" href="Digest/MD5.html">Digest::MD5</a> qw(md5);

139

<pre class="verbatim"> <a class="l_k" href="functions/use.html">use</a> Digest::MD5 qw(md5);

137

140

$digest = md5($message);</pre>

138

141

There are also versions of the functions with "_hex" or "_base64"

139

142

appended to the name, which returns the digest in the indicated form.

140

143

<a name="OO-INTERFACE"></a><h1>OO INTERFACE</h1>

141

The following methods are available for all <code class="inline">Digest::</code>

144

The following methods are available for all <code class="inline">Digest::</code>

142

145

modules:

143

146

<ul>

144

147

<li><a name="%24ctx-%3d-Digest-%3eXXX(%24arg%2c...)"></a>$ctx = Digest->XXX($arg,...)

167

170

<li><a name="%24ctx-%3ereset"></a>$ctx->reset

168

171

This is just an alias for $ctx->new.

169

172

</li>

170

<li><a name="%24ctx-%3eadd(-%24data%2c-...-)"></a>$ctx->add( $data, ... )

171

The $data provided as argument are appended to the message we

172

calculate the digest for. The return value is the $ctx object itself.

173

<li><a name="%24ctx-%3eadd(-%24data-)"></a>$ctx->add( $data )

174

</li>

175

<li><a name="%24ctx-%3eadd(-%24chunk1%2c-%24chunk2%2c-...-)"></a>$ctx->add( $chunk1, $chunk2, ... )

176

The string value of the $data provided as argument is appended to the

177

message we calculate the digest for. The return value is the $ctx

178

object itself.

179

If more arguments are provided then they are all appended to the

180

message, thus all these lines will have the same effect on the state

181

of the $ctx object:

182

<pre class="verbatim"> $ctx->add("a"); $ctx->add("b"); $ctx->add("c");

183

$ctx->add("a")->add("b")->add("c");

184

$ctx->add("a", "b", "c");

185

$ctx->add("abc");</pre>

186

Most algorithms are only defined for strings of bytes and this method

187

might therefore croak if the provided arguments contain chars with

188

ordinal number above 255.

173

189

</li>

174

190

<li><a name="%24ctx-%3eaddfile(-%24io_handle-)"></a>$ctx->addfile( $io_handle )

175

191

The $io_handle is read until EOF and the content is appended to the

176

192

message we calculate the digest for. The return value is the $ctx

177

193

object itself.

194

The addfile() method will croak() if it fails reading data for some

195

reason. If it croaks it is unpredictable what the state of the $ctx

196

object will be in. The addfile() method might have been able to read

197

the file partially before it failed. It is probably wise to discard

198

or reset the $ctx object if this occurs.

199

In most cases you want to make sure that the $io_handle is in

200

"binmode" before you pass it as argument to the addfile() method.

178

201

</li>

179

202

<li><a name="%24ctx-%3eadd_bits(-%24data%2c-%24nbits-)"></a>$ctx->add_bits( $data, $nbits )

180

203

</li>

181

204

<li><a name="%24ctx-%3eadd_bits(-%24bitstring-)"></a>$ctx->add_bits( $bitstring )

182

The bits provided are appended to the message we calculate the digest

183

for. The return value is the $ctx object itself.

205

The add_bits() method is an alternative to add() that allow partial

206

bytes to be appended to the message. Most users should just ignore

207

this method as partial bytes is very unlikely to be of any practical

208

use.

184

209

The two argument form of add_bits() will add the first $nbits bits

185

from data. For the last potentially partial byte only the high order

210

from $data. For the last potentially partial byte only the high order

186

211

<code class="inline">$nbits % 8</code>

187

212

bits are used. If $nbits is greater than <code class="inline"><a class="l_k" href="functions/length.html">length</a>($data) * 8</code>

188

213

, then this method would do the same as <code class="inline">$ctx->add($data)</code>

189

, that is $nbits is silently ignored.

214

.

190

215

The one argument form of add_bits() takes a $bitstring of "1" and "0"

191

216

chars as argument. It's a shorthand for <code class="inline">$ctx->add_bits(<a class="l_k" href="functions/pack.html">pack</a>("B*",

192

217

$bitstring), <a class="l_k" href="functions/length.html">length</a>($bitstring))</code>

193

218

.

219

The return value is the $ctx object itself.

194

220

This example shows two calls that should have the same effect:

195

221

<pre class="verbatim"> $ctx->add_bits("111100001010");

196

222

$ctx->add_bits("\xF0\xA0", 12);</pre>

197

Most digest algorithms are byte based. For those it is not possible

223

Most digest algorithms are byte based and for these it is not possible

198

224

to add bits that are not a multiple of 8, and the add_bits() method

199

225

will croak if you try.

200

226

</li>

201

227

<li><a name="%24ctx-%3edigest"></a>$ctx->digest

202

228

Return the binary digest for the message.

203

Note that the <code class="inline">digest</code>

229

Note that the <code class="inline">digest</code>

204

230

operation is effectively a destructive,

205

231

read-once operation. Once it has been performed, the $ctx object is

206

232

automatically <code class="inline"><a class="l_k" href="functions/reset.html">reset</a></code> and can be used to calculate another digest

207

233

value. Call $ctx->clone->digest if you want to calculate the digest

208

without reseting the digest state.

234

without resetting the digest state.

209

235

</li>

210

236

<li><a name="%24ctx-%3ehexdigest"></a>$ctx->hexdigest

211

237

Same as $ctx->digest, but will return the digest in hexadecimal form.

242

268

243

269

<a href="http://search.cpan.org/perldoc/Digest::Adler32">Digest::Adler32</a>, <a href="http://search.cpan.org/perldoc/Digest::CRC">Digest::CRC</a>, <a href="http://search.cpan.org/perldoc/Digest::Haval256">Digest::Haval256</a>,

244

270

<a href="http://search.cpan.org/perldoc/Digest::HMAC">Digest::HMAC</a>, <a href="http://search.cpan.org/perldoc/Digest::MD2">Digest::MD2</a>, <a href="http://search.cpan.org/perldoc/Digest::MD4">Digest::MD4</a>, <a href="Digest/MD5.html">Digest::MD5</a>,

245

<a href="http://search.cpan.org/perldoc/Digest::SHA">Digest::SHA</a>, <a href="http://search.cpan.org/perldoc/Digest::SHA1">Digest::SHA1</a>, <a href="http://search.cpan.org/perldoc/Digest::SHA2">Digest::SHA2</a>, <a href="http://search.cpan.org/perldoc/Digest::Whirlpool">Digest::Whirlpool</a>

271

<a href="Digest/SHA.html">Digest::SHA</a>, <a href="http://search.cpan.org/perldoc/Digest::SHA1">Digest::SHA1</a>, <a href="http://search.cpan.org/perldoc/Digest::SHA2">Digest::SHA2</a>, <a href="http://search.cpan.org/perldoc/Digest::Whirlpool">Digest::Whirlpool</a>

246

272

New digest implementations should consider subclassing from <a href="Digest/base.html">Digest::base</a>.

247

273

274

<a href="http://en.wikipedia.org/wiki/Cryptographic_hash_function">http://en.wikipedia.org/wiki/Cryptographic_hash_function</a>

248

275

<a name="AUTHOR"></a><h1>AUTHOR</h1>

249

276

Gisle Aas <gisle@aas.no>

250

The <code class="inline">Digest::</code>

277

The <code class="inline">Digest::</code>

251

278

interface is based on the interface originally

252

developed by Neil Winton for his <code class="inline">MD5</code>

279

developed by Neil Winton for his <code class="inline">MD5</code>

253

280

module.

254

281

This library is free software; you can redistribute it and/or

255

282

modify it under the same terms as Perl itself.

256

257

283

284

258

285

259

286

</div>

260

287

</div>

271

298

272

299

</form>

273

300

301

274

302

<h2>Labels:</h2>

275

303

276

304

Older »