diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Digest.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Digest.3perl | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Digest.3perl b/upstream/debian-unstable/man3/Digest.3perl new file mode 100644 index 00000000..688bd180 --- /dev/null +++ b/upstream/debian-unstable/man3/Digest.3perl @@ -0,0 +1,325 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Digest 3perl" +.TH Digest 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Digest \- Modules that calculate message digests +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 5 +\& $md5 = Digest\->new("MD5"); +\& $sha1 = Digest\->new("SHA\-1"); +\& $sha256 = Digest\->new("SHA\-256"); +\& $sha384 = Digest\->new("SHA\-384"); +\& $sha512 = Digest\->new("SHA\-512"); +\& +\& $hmac = Digest\->HMAC_MD5($key); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \f(CW\*(C`Digest::\*(C'\fR modules calculate digests, also called "fingerprints" +or "hashes", of some data, called a message. The digest is (usually) +some small/fixed size string. The actual size of the digest depend of +the algorithm used. The message is simply a sequence of arbitrary +bytes or bits. +.PP +An important property of the digest algorithms is that the digest is +\&\fIlikely\fR to change if the message change in some way. Another +property is that digest functions are one-way functions, that is it +should be \fIhard\fR to find a message that correspond to some given +digest. Algorithms differ in how "likely" and how "hard", as well as +how efficient they are to compute. +.PP +Note that the properties of the algorithms change over time, as the +algorithms are analyzed and machines grow faster. If your application +for instance depends on it being "impossible" to generate the same +digest for a different message it is wise to make it easy to plug in +stronger algorithms as the one used grow weaker. Using the interface +documented here should make it easy to change algorithms later. +.PP +All \f(CW\*(C`Digest::\*(C'\fR modules provide the same programming interface. A +functional interface for simple use, as well as an object oriented +interface that can handle messages of arbitrary length and which can +read files directly. +.PP +The digest can be delivered in three formats: +.IP \fIbinary\fR 8 +.IX Item "binary" +This is the most compact form, but it is not well suited for printing +or embedding in places that can't handle arbitrary data. +.IP \fIhex\fR 8 +.IX Item "hex" +A twice as long string of lowercase hexadecimal digits. +.IP \fIbase64\fR 8 +.IX Item "base64" +A string of portable printable characters. This is the base64 encoded +representation of the digest with any trailing padding removed. The +string will be about 30% longer than the binary version. +MIME::Base64 tells you more about this encoding. +.PP +The functional interface is simply importable functions with the same +name as the algorithm. The functions take the message as argument and +return the digest. Example: +.PP +.Vb 2 +\& use Digest::MD5 qw(md5); +\& $digest = md5($message); +.Ve +.PP +There are also versions of the functions with "_hex" or "_base64" +appended to the name, which returns the digest in the indicated form. +.SH "OO INTERFACE" +.IX Header "OO INTERFACE" +The following methods are available for all \f(CW\*(C`Digest::\*(C'\fR modules: +.ie n .IP "$ctx = Digest\->XXX($arg,...)" 4 +.el .IP "\f(CW$ctx\fR = Digest\->XXX($arg,...)" 4 +.IX Item "$ctx = Digest->XXX($arg,...)" +.PD 0 +.ie n .IP "$ctx = Digest\->new(XXX => $arg,...)" 4 +.el .IP "\f(CW$ctx\fR = Digest\->new(XXX => \f(CW$arg\fR,...)" 4 +.IX Item "$ctx = Digest->new(XXX => $arg,...)" +.ie n .IP "$ctx = Digest::XXX\->new($arg,...)" 4 +.el .IP "\f(CW$ctx\fR = Digest::XXX\->new($arg,...)" 4 +.IX Item "$ctx = Digest::XXX->new($arg,...)" +.PD +The constructor returns some object that encapsulate the state of the +message-digest algorithm. You can add data to the object and finally +ask for the digest. The "XXX" should of course be replaced by the proper +name of the digest algorithm you want to use. +.Sp +The two first forms are simply syntactic sugar which automatically +load the right module on first use. The second form allow you to use +algorithm names which contains letters which are not legal perl +identifiers, e.g. "SHA\-1". If no implementation for the given algorithm +can be found, then an exception is raised. +.Sp +To know what arguments (if any) the constructor takes (the \f(CW\*(C`$args,...\*(C'\fR above) +consult the docs for the specific digest implementation. +.Sp +If \fBnew()\fR is called as an instance method (i.e. \f(CW$ctx\fR\->new) it will just +reset the state the object to the state of a newly created object. No +new object is created in this case, and the return value is the +reference to the object (i.e. \f(CW$ctx\fR). +.ie n .IP "$other_ctx = $ctx\->clone" 4 +.el .IP "\f(CW$other_ctx\fR = \f(CW$ctx\fR\->clone" 4 +.IX Item "$other_ctx = $ctx->clone" +The clone method creates a copy of the digest state object and returns +a reference to the copy. +.ie n .IP $ctx\->reset 4 +.el .IP \f(CW$ctx\fR\->reset 4 +.IX Item "$ctx->reset" +This is just an alias for \f(CW$ctx\fR\->new. +.ie n .IP "$ctx\->add( $data )" 4 +.el .IP "\f(CW$ctx\fR\->add( \f(CW$data\fR )" 4 +.IX Item "$ctx->add( $data )" +.PD 0 +.ie n .IP "$ctx\->add( $chunk1, $chunk2, ... )" 4 +.el .IP "\f(CW$ctx\fR\->add( \f(CW$chunk1\fR, \f(CW$chunk2\fR, ... )" 4 +.IX Item "$ctx->add( $chunk1, $chunk2, ... )" +.PD +The string value of the \f(CW$data\fR provided as argument is appended to the +message we calculate the digest for. The return value is the \f(CW$ctx\fR +object itself. +.Sp +If more arguments are provided then they are all appended to the +message, thus all these lines will have the same effect on the state +of the \f(CW$ctx\fR object: +.Sp +.Vb 4 +\& $ctx\->add("a"); $ctx\->add("b"); $ctx\->add("c"); +\& $ctx\->add("a")\->add("b")\->add("c"); +\& $ctx\->add("a", "b", "c"); +\& $ctx\->add("abc"); +.Ve +.Sp +Most algorithms are only defined for strings of bytes and this method +might therefore croak if the provided arguments contain chars with +ordinal number above 255. +.ie n .IP "$ctx\->addfile( $io_handle )" 4 +.el .IP "\f(CW$ctx\fR\->addfile( \f(CW$io_handle\fR )" 4 +.IX Item "$ctx->addfile( $io_handle )" +The \f(CW$io_handle\fR is read until EOF and the content is appended to the +message we calculate the digest for. The return value is the \f(CW$ctx\fR +object itself. +.Sp +The \fBaddfile()\fR method will \fBcroak()\fR if it fails reading data for some +reason. If it croaks it is unpredictable what the state of the \f(CW$ctx\fR +object will be in. The \fBaddfile()\fR method might have been able to read +the file partially before it failed. It is probably wise to discard +or reset the \f(CW$ctx\fR object if this occurs. +.Sp +In most cases you want to make sure that the \f(CW$io_handle\fR is in +"binmode" before you pass it as argument to the \fBaddfile()\fR method. +.ie n .IP "$ctx\->add_bits( $data, $nbits )" 4 +.el .IP "\f(CW$ctx\fR\->add_bits( \f(CW$data\fR, \f(CW$nbits\fR )" 4 +.IX Item "$ctx->add_bits( $data, $nbits )" +.PD 0 +.ie n .IP "$ctx\->add_bits( $bitstring )" 4 +.el .IP "\f(CW$ctx\fR\->add_bits( \f(CW$bitstring\fR )" 4 +.IX Item "$ctx->add_bits( $bitstring )" +.PD +The \fBadd_bits()\fR method is an alternative to \fBadd()\fR that allow partial +bytes to be appended to the message. Most users can just ignore +this method since typical applications involve only whole-byte data. +.Sp +The two argument form of \fBadd_bits()\fR will add the first \f(CW$nbits\fR bits +from \f(CW$data\fR. For the last potentially partial byte only the high order +\&\f(CW\*(C`$nbits % 8\*(C'\fR bits are used. If \f(CW$nbits\fR is greater than \f(CW\*(C`length($data) * 8\*(C'\fR, then this method would do the same as \f(CW\*(C`$ctx\->add($data)\*(C'\fR. +.Sp +The one argument form of \fBadd_bits()\fR takes a \f(CW$bitstring\fR of "1" and "0" +chars as argument. It's a shorthand for \f(CW\*(C`$ctx\->add_bits(pack("B*", +$bitstring), length($bitstring))\*(C'\fR. +.Sp +The return value is the \f(CW$ctx\fR object itself. +.Sp +This example shows two calls that should have the same effect: +.Sp +.Vb 2 +\& $ctx\->add_bits("111100001010"); +\& $ctx\->add_bits("\exF0\exA0", 12); +.Ve +.Sp +Most digest algorithms are byte based and for these it is not possible +to add bits that are not a multiple of 8, and the \fBadd_bits()\fR method +will croak if you try. +.ie n .IP $ctx\->digest 4 +.el .IP \f(CW$ctx\fR\->digest 4 +.IX Item "$ctx->digest" +Return the binary digest for the message. +.Sp +Note that the \f(CW\*(C`digest\*(C'\fR operation is effectively a destructive, +read-once operation. Once it has been performed, the \f(CW$ctx\fR object is +automatically \f(CW\*(C`reset\*(C'\fR and can be used to calculate another digest +value. Call \f(CW$ctx\fR\->clone\->digest if you want to calculate the digest +without resetting the digest state. +.ie n .IP $ctx\->hexdigest 4 +.el .IP \f(CW$ctx\fR\->hexdigest 4 +.IX Item "$ctx->hexdigest" +Same as \f(CW$ctx\fR\->digest, but will return the digest in hexadecimal form. +.ie n .IP $ctx\->b64digest 4 +.el .IP \f(CW$ctx\fR\->b64digest 4 +.IX Item "$ctx->b64digest" +Same as \f(CW$ctx\fR\->digest, but will return the digest as a base64 encoded +string without padding. +.ie n .IP $ctx\->base64_padded_digest 4 +.el .IP \f(CW$ctx\fR\->base64_padded_digest 4 +.IX Item "$ctx->base64_padded_digest" +Same as \f(CW$ctx\fR\->digest, but will return the digest as a base64 encoded +string. +.SH "Digest speed" +.IX Header "Digest speed" +This table should give some indication on the relative speed of +different algorithms. It is sorted by throughput based on a benchmark +done with of some implementations of this API: +.PP +.Vb 1 +\& Algorithm Size Implementation MB/s +\& +\& MD4 128 Digest::MD4 v1.3 165.0 +\& MD5 128 Digest::MD5 v2.33 98.8 +\& SHA\-256 256 Digest::SHA2 v1.1.0 66.7 +\& SHA\-1 160 Digest::SHA v4.3.1 58.9 +\& SHA\-1 160 Digest::SHA1 v2.10 48.8 +\& SHA\-256 256 Digest::SHA v4.3.1 41.3 +\& Haval\-256 256 Digest::Haval256 v1.0.4 39.8 +\& SHA\-384 384 Digest::SHA2 v1.1.0 19.6 +\& SHA\-512 512 Digest::SHA2 v1.1.0 19.3 +\& SHA\-384 384 Digest::SHA v4.3.1 19.2 +\& SHA\-512 512 Digest::SHA v4.3.1 19.2 +\& Whirlpool 512 Digest::Whirlpool v1.0.2 13.0 +\& MD2 128 Digest::MD2 v2.03 9.5 +\& +\& Adler\-32 32 Digest::Adler32 v0.03 1.3 +\& CRC\-16 16 Digest::CRC v0.05 1.1 +\& CRC\-32 32 Digest::CRC v0.05 1.1 +\& MD5 128 Digest::Perl::MD5 v1.5 1.0 +\& CRC\-CCITT 16 Digest::CRC v0.05 0.8 +.Ve +.PP +These numbers was achieved Apr 2004 with ActivePerl\-5.8.3 running +under Linux on a P4 2.8 GHz CPU. The last 5 entries differ by being +pure perl implementations of the algorithms, which explains why they +are so slow. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Digest::Adler32, Digest::CRC, Digest::Haval256, +Digest::HMAC, Digest::MD2, Digest::MD4, Digest::MD5, +Digest::SHA, Digest::SHA1, Digest::SHA2, Digest::Whirlpool +.PP +New digest implementations should consider subclassing from Digest::base. +.PP +MIME::Base64 +.PP +http://en.wikipedia.org/wiki/Cryptographic_hash_function +.SH AUTHOR +.IX Header "AUTHOR" +Gisle Aas <gisle@aas.no> +.PP +The \f(CW\*(C`Digest::\*(C'\fR interface is based on the interface originally +developed by Neil Winton for his \f(CW\*(C`MD5\*(C'\fR module. +.PP +This library is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +.Vb 2 +\& Copyright 1998\-2006 Gisle Aas. +\& Copyright 1995,1996 Neil Winton. +.Ve |