document OpenBSD::md5

3 files changed, 97 insertions, 8 deletions

diff --git a/usr.sbin/pkg_add/Makefile b/usr.sbin/pkg_add/Makefile
index 7167c98c21b..6acac7668ef 100644
--- a/usr.sbin/pkg_add/Makefile
+++ b/usr.sbin/pkg_add/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.71 2011/08/26 09:02:30 espie Exp $
+# $OpenBSD: Makefile,v 1.72 2012/01/15 14:16:16 espie Exp $
 
 .include <bsd.own.mk>
 
@@ -87,6 +87,7 @@ SCRIPTS_LNK = \
 LIBBASE=/usr/libdata/perl5
 
 PODS= \
+    OpenBSD::md5 \
     OpenBSD::Getopt \
     OpenBSD::IdCache \
     OpenBSD::Intro \
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
index e9c6cf0ebe9..959c53c27f8 100644
--- a/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
+++ b/usr.sbin/pkg_add/pod/OpenBSD::Intro.pod
@@ -1,4 +1,4 @@
-$OpenBSD: OpenBSD::Intro.pod,v 1.16 2011/08/31 09:18:47 espie Exp $
+$OpenBSD: OpenBSD::Intro.pod,v 1.17 2012/01/15 14:16:16 espie Exp $
 
 =head1 NAME
 
@@ -102,11 +102,11 @@ Package names and specifications for package names have a specific format,
 which is described in L<packages-specs(7)>.   Package specs are objects
 created in L<OpenBSD::PkgSpec(3p)>, which are then compared to objects
 created in L<OpenBSD::PackageName(3p)>.  Both classes contain further functions
-for high level manipulation of names and specs. 
-There is also a framework to organize searches based on L<OpenBSD::Search(3p)> 
-objects.  Specifications are structured in a specific way, which yields 
-a shorthand for conflict handling through L<OpenBSD::PkgCfl(3p)>, 
-allows the package system to resolve dependencies in 
+for high level manipulation of names and specs.
+There is also a framework to organize searches based on L<OpenBSD::Search(3p)>
+objects.  Specifications are structured in a specific way, which yields
+a shorthand for conflict handling through L<OpenBSD::PkgCfl(3p)>,
+allows the package system to resolve dependencies in
 L<OpenBSD::Dependencies(3p)> and to figure out package
 updates in L<OpenBSD::Update(3p)>.
 
@@ -582,7 +582,7 @@ virtual file system (pretend) operations.
 
 =item OpenBSD::md5
 
-simple interface to the L<Digest::MD5(3p)> module.
+simple interface to the L<Digest::MD5(3p)> and L<Digest::SHA(3p)> modules.
 
 =item OpenBSD::x509
 
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::md5.pod b/usr.sbin/pkg_add/pod/OpenBSD::md5.pod
new file mode 100644
index 00000000000..409f2efa33f
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::md5.pod
@@ -0,0 +1,88 @@
+$OpenBSD: OpenBSD::md5.pod,v 1.1 2012/01/15 14:16:16 espie Exp $
+
+=head1 NAME
+
+OpenBSD::md5 - simple interface to md5 and sha256 digests
+
+=head1 SYNOPSIS
+
+    use OpenBSD::md5;
+
+    my $md5 = OpenBSD::md5->new($filename);
+    $k->{$md5->key} = $filename;
+
+    my $ck2 = $md5->new($filename2);
+
+    if ($ck2->equals(md5)) {
+         ...
+    }
+
+    print $md5->stringize # provides an hex representation
+
+    my $ck3 = OpenBSD::sha->new($filename);
+    !$ck3->equals($ck2); # comparing is okay, but will never match
+    my $s = $ck3->stringize; # base64 representation
+
+    my $ck4 = $s->fromstring; # decodes both base64 and hex
+	
+
+
+=head1 DESCRIPTION
+
+C<OpenBSD::md5> provides an object-oriented interface to cryptographic
+hashing facilities for use in the ports tree.
+
+In particular, it provides an abstraction to build crypto hashes from
+files, convert from and to text, and compare two checksums while
+keeping the user from making low-level decisions.
+
+There are two classes, C<OpenBSD::md5> and C<OpenBSD::sha> which provide the
+same facilities, respectively for md5 and sha256 digests.
+
+The module itself is called C<OpenBSD::md5> for historical reasons.
+Support for md5 digests is there for legacy reasons, all new code should
+produce and write sha256 digests only.
+
+=over 8
+
+=item $o = $class-E<gt>new($filename)
+
+create a new digest object from the contents of a file.
+
+=item $o = $class-E<gt>fromstring($string)
+
+create a new digest object from a string representation.
+
+=item $o2 = $o-E<gt>new($filename) / $o-E<gt>fromstring($string)
+
+create a new digest object C<$o2> of the same type as C<$o>.
+This can be used to compare a file against an existing digest, which may
+well be of md5 type in very old packages. Even though the use of md5
+is deprecated, checking md5 checksums is still slightly better than nothing...
+
+=item $o-E<gt>equal($o2)
+
+compare two digest objects. Returns true only if they're of the same type
+and they match.
+
+=item $h{$o-E<gt>key} = ...
+
+return the actual digest as a binary string, for use as a key in hashing.
+
+=item $s = $o-E<gt>stringize
+
+convert the digest into a suitable text representation.
+
+=item $o-E<gt>write($fh)
+
+writes an appropriate digest annotation on a packing-list filehandle
+(see L<OpenBSD::PackingList(3p)> and L<pkg_create(1)>).
+
+=back
+
+=head1 SEE ALSO
+
+L<cksum(1)> ,
+L<Digest::MD5(3p)> ,
+L<Digest::SHA(3p)> ,
+L<Mime::Base64(3p)>