Digest

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
• ОБЪЕКТНЫЙ ИНТЕРФЕЙС
• Скорость Digest
• СМОТРИТЕ ТАКЖЕ
• АВТОР

ИМЯ

Digest - Модули, которые вычисляют дайджесты сообщений

СИНТАКСИС

$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);

ОПИСАНИЕ

Модули Digest:: вычисляют дайджесты, также называемые «отпечатками» или «хешами», некоторой данных, называемых сообщением. Дайджест представляет собой (обычно) строку малого/фиксированного размера. Фактический размер дайджеста зависит от используемого алгоритма. Сообщение представляет собой просто последовательность произвольных байтов или битов.

Важным свойством алгоритмов дайджестов является то, что дайджест, вероятно, изменится, если сообщение изменится каким-либо образом. Другим свойством является то, что функции дайджестов являются односторонними функциями, то есть должно быть сложно найти сообщение, соответствующее данному дайджесту. Алгоритмы различаются по тому, насколько «вероятно» и насколько «сложно», а также по эффективности вычисления.

Обратите внимание, что свойства алгоритмов со временем изменяются, поскольку алгоритмы анализируются, а машины становятся быстрее. Если ваше приложение, например, зависит от того, что «невозможно» сгенерировать один и тот же дайджест для другого сообщения, разумно сделать так, чтобы было легко подключать более сильные алгоритмы, поскольку используемые алгоритмы становятся слабее. Использование интерфейса, описанного здесь, должно упростить изменение алгоритмов в будущем.

Все модули Digest:: предоставляют одинаковый интерфейс программирования. Функциональный интерфейс для простого использования, а также объектно-ориентированный интерфейс, который может обрабатывать сообщения произвольной длины и может читать файлы напрямую.

Дайджест может быть представлен в трех форматах:

двоичный

Это наиболее компактная форма, но она не подходит для печати или вставки в места, которые не могут обрабатывать произвольные данные.

шестнадцатеричный

Строка вдвое большей длины из строчных шестнадцатеричных цифр.

base64

Строка портативных печатаемых символов. Это кодировка дайджеста в base64 без последующего заполнения. Строка будет примерно на 30% длиннее, чем двоичная версия. MIME::Base64 расскажет вам больше об этом кодировании.

Функциональный интерфейс — это просто импортируемые функции с тем же именем, что и алгоритм. Функции принимают сообщение в качестве аргумента и возвращают дайджест. Пример:

use Digest::MD5 qw(md5);
$digest = md5($message);

Также существуют версии функций с добавленным "_hex" или "_base64", которые возвращают дайджест в указанной форме.

ОБЪЕКТНЫЙ ИНТЕРФЕЙС

Для всех модулей Digest:: доступны следующие методы:

$ctx = Digest->XXX($arg,...)

$ctx = Digest->new(XXX => $arg,...)

$ctx = Digest::XXX->new($arg,...)

Конструктор возвращает некоторый объект, который инкапсулирует состояние алгоритма вычисления дайджеста сообщения. Вы можете добавить данные в объект и, в конечном итоге, запросить дайджест. "XXX", разумеется, должен быть заменён на соответствующее название алгоритма вычисления дайджеста.

Первые два варианта просто синтаксический сахар, который автоматически загружает нужный модуль при первом использовании. Второй вариант позволяет использовать имена алгоритмов, содержащие символы, которые не являются допустимыми идентификаторами Perl, например, "SHA-1". Если реализация для данного алгоритма не найдена, то генерируется исключение.

Чтобы узнать, какие аргументы (если таковые имеются) принимает конструктор (см. $args,...), обратитесь к документации конкретной реализации алгоритма вычисления дайджеста.

Если new() вызывается как метод экземпляра (т.е. $ctx->new), он просто сбрасывает состояние объекта до состояния вновь созданного объекта. В этом случае новый объект не создаётся, а возвращается ссылка на объект (т.е. $ctx).

$other_ctx = $ctx->clone

Метод clone создаёт копию объекта состояния вычисления дайджеста и возвращает ссылку на копию.

$ctx->reset

Это просто псевдоним для $ctx->new.

$ctx->add( $data )

$ctx->add( $chunk1, $chunk2, ... )

Строковое значение аргумента $data добавляется к сообщению, для которого мы вычисляем дайджест. Возвращаемым значением является сам объект $ctx.

Если предоставлено несколько аргументов, они все добавляются к сообщению, поэтому все эти строки окажут одинаковое влияние на состояние объекта $ctx:

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

Большинство алгоритмов определены только для строк байтов, и поэтому этот метод может выдавать ошибку, если предоставленные аргументы содержат символы с порядковым номером выше 255.

$ctx->addfile( $io_handle )

Файл, связанный с $io_handle, читается до конца файла, и его содержимое добавляется к сообщению, для которого мы вычисляем дайджест. Возвращаемым значением является сам объект $ctx.

Метод addfile() выдаст ошибку (croak()), если произойдёт ошибка при чтении данных. Если произошла ошибка, поведение объекта $ctx непредсказуемо. Возможно, метод addfile() успел прочитать часть файла перед ошибкой. Вероятно, в этом случае следует удалить или сбросить объект $ctx.

В большинстве случаев необходимо убедиться, что $io_handle находится в режиме "binmode", прежде чем передавать его в качестве аргумента методу addfile().

$ctx->add_bits( $data, $nbits )

$ctx->add_bits( $bitstring )

Метод add_bits() — это альтернатива методу add(), которая позволяет добавлять к сообщению частичные байты. Большинство пользователей могут проигнорировать этот метод, поскольку типичные приложения включают только данные целых байтов.

В версии add_bits() с двумя аргументами добавляются первые $nbits биты из $data. Для последнего потенциально частичного байта используются только старшие $nbits % 8 биты. Если $nbits больше length($data) * 8, то этот метод выполнит то же, что и $ctx->add($data).

В версии add_bits() с одним аргументом принимается строка $bitstring из символов "1" и "0". Это сокращение для $ctx->add_bits(pack("B*", $bitstring), length($bitstring)).

Возвращаемым значением является сам объект $ctx.

Этот пример демонстрирует два вызова, которые должны иметь одинаковый эффект:

$ctx->add_bits("111100001010");
$ctx->add_bits("\xF0\xA0", 12);

Большинство алгоритмов вычисления дайджестов основаны на байтах, и для них невозможно добавить биты, которые не являются кратными 8, и метод add_bits() выдаст ошибку, если вы попробуете это сделать.

$ctx->digest

Возвращает двоичный дайджест сообщения.

Обратите внимание, что операция digest фактически является деструктивной операцией, которая читается только один раз. После её выполнения объект $ctx автоматически reset и может быть использован для вычисления другого значения дайджеста. Используйте $ctx->clone->digest, если вы хотите вычислить дайджест, не сбрасывая состояние вычисления дайджеста.

$ctx->hexdigest

То же самое, что и $ctx->digest, но возвращает дайджест в шестнадцатеричном формате.

$ctx->b64digest

То же самое, что и $ctx->digest, но возвращает дайджест в формате base64 без заполнения.

$ctx->base64_padded_digest

То же самое, что и $ctx->digest, но возвращает дайджест в формате base64 с заполнением.

Скорость вычисления дайджестов

Эта таблица должна дать некоторое представление о относительной скорости различных алгоритмов. Она отсортирована по пропускной способности на основе эталонного теста, выполненного с некоторыми реализациями этого API:

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

Эти значения были получены в апреле 2004 года с ActivePerl-5.8.3, работающим под Linux на процессоре P4 2.8 ГГц. Последние 5 записей отличаются тем, что представляют собой чисто перловые реализации алгоритмов, что объясняет, почему они так медленны.

См. также

Digest::Adler32, Digest::CRC, Digest::Haval256, Digest::HMAC, Digest::MD2, Digest::MD4, Digest::MD5, Digest::SHA, Digest::SHA1, Digest::SHA2, Digest::Whirlpool

Новые реализации дайджестов должны рассматривать возможность наследования от Digest::base.

MIME::Base64

http://en.wikipedia.org/wiki/Cryptographic_hash_function

АВТОР

Gisle Aas <gisle@aas.no>

Интерфейс Digest:: основан на интерфейсе, первоначально разработанном Нилом Винтоном для его MD5 модуля.

Эта библиотека — свободное программное обеспечение; вы можете распространять и/или изменять её в соответствии с теми же условиями, что и Perl сам по себе.

Copyright 1998-2006 Gisle Aas.
Copyright 1995,1996 Neil Winton.