Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 325 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Digest.3pm b/upstream/mageia-cauldron/man3pm/Digest.3pm
new file mode 100644
index 00000000..6b9afd2b
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Digest.3pm
@@ -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 3pm"
+.TH Digest 3pm 2023-11-28 "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