R: Create hash function digests for arbitrary R objects
digest
R Documentation
Create hash function digests for arbitrary R objects
Description
The digest function applies a cryptographical hash function to
arbitrary R objects. By default, the objects are internally
serialized, and either one of the currently implemented MD5 and SHA-1
hash functions algorithms can be used to compute a compact digest of
the serialized object.
In order to compare this implementation with others, serialization of
the input argument can also be turned off in which the input argument
must be a character string for which its digest is returned.
An arbitrary R object which will then be passed to the
serialize function, unless the serialize
argument is set to FALSE.
algo
The algorithms to be used; currently available choices are
md5, which is also the default, sha1, crc32,
sha256, sha512, xxhash32, xxhash64 and
murmur32.
serialize
A logical variable indicating whether the object
should be serialized using serialize (in ASCII
form). Setting this to FALSE allows to compare the digest
output of given character strings to known control output. It also
allows the use of raw vectors such as the output of non-ASCII
serialization.
file
A logical variable indicating whether the object is a file
name or a file name if object is not specified.
length
Number of characters to process. By default, when
length is set to Inf, the whole string or file is
processed.
skip
Number of input bytes to skip before calculating the
digest. Negative values are invalid and currently treated as zero.
Special value "auto" will cause serialization header to be
skipped if serialize is set to TRUE (the serialization
header contains the R version number thus skipping it allows the
comparison of hashes across platforms and some R versions).
ascii
This flag is passed to the serialize function if
serialize is set to TRUE, determining whether the hash
is computed on the ASCII or binary representation.
raw
A logical variable with a default value of FALSE, implying
digest returns digest output as ASCII hex values. Set to TRUE
to return digest output in raw (binary) form.
seed
an integer to seed the random number generator. This is only
used in the xxhash32, xxhash64 and murmur32 functions
and can be used to generate additional hashes for the same input if
desired.
errormode
A character value denoting a choice for the behaviour in
the case of error: ‘stop’ aborts (and is the default value),
‘warn’ emits a warning and returns NULL and
‘silent’ suppresses the error and returns an empty string.
Details
Cryptographic hash functions are well researched and documented. The
MD5 algorithm by Ron Rivest is specified in RFC 1321. The SHA-1
algorithm is specified in FIPS-180-1, SHA-2 is described in
FIPS-180-2.
For md5, sha-1 and sha-256, this R implementation relies on standalone
implementations in C by Christophe Devine. For crc32, code from the
zlib library by Jean-loup Gailly and Mark Adler is used.
For sha-512, a standalone implementation from Aaron Gifford is used.
For xxhash32 and xxhash64, the reference implementation by Yann Collet is used.
For murmur32, the progressive implementation by Shane Day is used.
Please note that this package is not meant to be used for
cryptographic purposes for which more comprehensive (and widely
tested) libraries such as OpenSSL should be used. Also, it is known
that crc32 is not collision-proof. For sha-1, recent results indicate
certain cryptographic weaknesses as well. For more details, see for example
http://www.schneier.com/blog/archives/2005/02/cryptanalysis_o.html.
Value
The digest function returns a character string of a fixed
length containing the requested digest of the supplied R object. This
string is of length 32 for MD5; of length 40 for SHA-1; of length 8
for CRC32 a string; of length 8 for for xxhash32; of length 16 for
xxhash64; and of length 8 for murmur32.
Author(s)
Dirk Eddelbuettel edd@debian.org for the R interface;
Antoine Lucas for the integration of crc32; Jarek Tuszynski for the
file-based operations; Henrik Bengtsson and Simon Urbanek for improved
serialization patches; Christophe Devine for the hash function
implementations for sha-1, sha-256 and md5; Jean-loup Gailly and Mark Adler
for crc32; Hannes Muehleisen for the integration of sha-512; Jim Hester for
the integration of xxhash32, xxhash64 and murmur32.