class OpenSSL::HMAC

Parent:: Объект

OpenSSL::HMAC позволяет вычислять код аутентификации сообщений на основе хеша (HMAC). Это тип кода аутентификации сообщений (MAC), включающий хеш-функцию в сочетании с ключом. HMAC может использоваться для проверки целостности сообщения, а также подлинности.

OpenSSL::HMAC имеет интерфейс, аналогичный интерфейсу OpenSSL::Digest.

HMAC-SHA256 с использованием одноразового интерфейса

key = "key"
data = "message-to-be-authenticated"
mac = OpenSSL::HMAC.hexdigest("SHA256", key, data)
#=> "cddb0db23f469c8bf072b21fd837149bd6ace9ab771cceef14c9e517cc93282e"

HMAC-SHA256 с использованием инкрементального интерфейса

data1 = File.binread("file1")
data2 = File.binread("file2")
key = "key"
hmac = OpenSSL::HMAC.new(key, 'SHA256')
hmac << data1
hmac << data2
mac = hmac.digest

Публичные методы класса

base64digest(digest, key, data) → aString

Исходный код

# File ext/openssl/lib/openssl/hmac.rb, line 73
def base64digest(digest, key, data)
  [digest(digest, key, data)].pack("m0")
end

Возвращает код аутентификации в виде строки, закодированной в Base64. Параметр digest задаёт используемый алгоритм хеширования. Это может быть String, представляющий имя алгоритма, или экземпляр OpenSSL::Digest.

Пример

key = 'key'
data = 'The quick brown fox jumps over the lazy dog'

hmac = OpenSSL::HMAC.base64digest('SHA1', key, data)
#=> "3nybhbi3iqa8ino29wqQcBydtNk="

digest(digest, key, data) → aString

Исходный код

# File ext/openssl/lib/openssl/hmac.rb, line 35
def digest(digest, key, data)
  hmac = new(key, digest)
  hmac << data
  hmac.digest
end

Возвращает код аутентификации в виде двоичной строки. Параметр digest задаёт используемый алгоритм хеширования. Это может быть String, представляющий имя алгоритма, или экземпляр OpenSSL::Digest.

Пример

key = 'key'
data = 'The quick brown fox jumps over the lazy dog'

hmac = OpenSSL::HMAC.digest('SHA1', key, data)
#=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9"

hexdigest(digest, key, data) → aString

Исходный код

# File ext/openssl/lib/openssl/hmac.rb, line 54
def hexdigest(digest, key, data)
  hmac = new(key, digest)
  hmac << data
  hmac.hexdigest
end

Возвращает код аутентификации в виде строки, закодированной в шестнадцатеричном формате. Параметр digest задаёт используемый алгоритм хеширования. Это может быть String, представляющий имя алгоритма, или экземпляр OpenSSL::Digest.

Пример

key = 'key'
data = 'The quick brown fox jumps over the lazy dog'

hmac = OpenSSL::HMAC.hexdigest('SHA1', key, data)
#=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9"

new(key, digest) → hmac

Исходный код

static VALUE
ossl_hmac_initialize(VALUE self, VALUE key, VALUE digest)
{
    EVP_MD_CTX *ctx;
    EVP_PKEY *pkey;

    GetHMAC(self, ctx);
    StringValue(key);
#ifdef HAVE_EVP_PKEY_NEW_RAW_PRIVATE_KEY
    pkey = EVP_PKEY_new_raw_private_key(EVP_PKEY_HMAC, NULL,
                                        (unsigned char *)RSTRING_PTR(key),
                                        RSTRING_LENINT(key));
    if (!pkey)
        ossl_raise(eHMACError, "EVP_PKEY_new_raw_private_key");
#else
    pkey = EVP_PKEY_new_mac_key(EVP_PKEY_HMAC, NULL,
                                (unsigned char *)RSTRING_PTR(key),
                                RSTRING_LENINT(key));
    if (!pkey)
        ossl_raise(eHMACError, "EVP_PKEY_new_mac_key");
#endif
    if (EVP_DigestSignInit(ctx, NULL, ossl_evp_get_digestbyname(digest),
                           NULL, pkey) != 1) {
        EVP_PKEY_free(pkey);
        ossl_raise(eHMACError, "EVP_DigestSignInit");
    }
    /* Decrement reference counter; EVP_MD_CTX still keeps it */
    EVP_PKEY_free(pkey);

    return self;
}

Возвращает экземпляр OpenSSL::HMAC, настроенный с заданным ключом и алгоритмом хеширования. Экземпляр представляет начальное состояние кода аутентификации сообщения до обработки каких-либо данных. Для обработки данных с ним используйте метод экземпляра update с вашими данными в качестве аргумента.

Пример

key = 'key'
instance = OpenSSL::HMAC.new(key, 'SHA1')
#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
instance.class
#=> OpenSSL::HMAC

Примечание о сравнениях

Два экземпляра можно безопасно сравнить с помощью == в режиме постоянного времени:

    other_instance = OpenSSL::HMAC.new('key', 'SHA1')
#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
instance == other_instance
#=> true

Публичные методы экземпляра

Псевдоним для: update

== (other)

Исходный код

# File ext/openssl/lib/openssl/hmac.rb, line 6
def ==(other)
  return false unless HMAC === other
  return false unless self.digest.bytesize == other.digest.bytesize

  OpenSSL.fixed_length_secure_compare(self.digest, other.digest)
end

Безопасное сравнение с другим экземпляром HMAC в режиме постоянного времени.

base64digest → строка

Исходный код

# File ext/openssl/lib/openssl/hmac.rb, line 17
def base64digest
  [digest].pack("m0")
end

Возвращает код аутентификации в виде строки, закодированной в Base64.

digest → строка

Исходный код

static VALUE
ossl_hmac_digest(VALUE self)
{
    EVP_MD_CTX *ctx;
    size_t buf_len = EVP_MAX_MD_SIZE;
    VALUE ret;

    GetHMAC(self, ctx);
    ret = rb_str_new(NULL, EVP_MAX_MD_SIZE);
    if (EVP_DigestSignFinal(ctx, (unsigned char *)RSTRING_PTR(ret),
                            &buf_len) != 1)
        ossl_raise(eHMACError, "EVP_DigestSignFinal");
    rb_str_set_len(ret, (long)buf_len);

    return ret;
}

Возвращает код аутентификации, представленный экземпляром, в виде двоичной строки.

Пример

instance = OpenSSL::HMAC.new('key', 'SHA1')
#=> f42bb0eeb018ebbd4597ae7213711ec60760843f
instance.digest
#=> "\xF4+\xB0\xEE\xB0\x18\xEB\xBDE\x97\xAEr\x13q\x1E\xC6\a`\x84?"

hexdigest → строка

Исходный код

static VALUE
ossl_hmac_hexdigest(VALUE self)
{
    EVP_MD_CTX *ctx;
    unsigned char buf[EVP_MAX_MD_SIZE];
    size_t buf_len = EVP_MAX_MD_SIZE;
    VALUE ret;

    GetHMAC(self, ctx);
    if (EVP_DigestSignFinal(ctx, buf, &buf_len) != 1)
        ossl_raise(eHMACError, "EVP_DigestSignFinal");
    ret = rb_str_new(NULL, buf_len * 2);
    ossl_bin2hex(buf, RSTRING_PTR(ret), buf_len);

    return ret;
}

Возвращает код аутентификации, представленный экземпляром, в виде строки, закодированной в шестнадцатеричном формате.

Также псевдоним для: inspect, to_s

initialize_copy (p1)

Исходный код

static VALUE
ossl_hmac_copy(VALUE self, VALUE other)
{
    EVP_MD_CTX *ctx1, *ctx2;

    rb_check_frozen(self);
    if (self == other) return self;

    GetHMAC(self, ctx1);
    GetHMAC(other, ctx2);
    if (EVP_MD_CTX_copy(ctx1, ctx2) != 1)
        ossl_raise(eHMACError, "EVP_MD_CTX_copy");
    return self;
}

inspect

Псевдоним для: hexdigest

reset → self

Исходный код

static VALUE
ossl_hmac_reset(VALUE self)
{
    EVP_MD_CTX *ctx;
    EVP_PKEY *pkey;

    GetHMAC(self, ctx);
    pkey = EVP_PKEY_CTX_get0_pkey(EVP_MD_CTX_get_pkey_ctx(ctx));
    if (EVP_DigestSignInit(ctx, NULL, EVP_MD_CTX_get0_md(ctx), NULL, pkey) != 1)
        ossl_raise(eHMACError, "EVP_DigestSignInit");

    return self;
}

Возвращает hmac в том состоянии, в котором он был первоначально инициализирован, при этом все обработанные данные из него удаляются.

Пример

data = "The quick brown fox jumps over the lazy dog"
instance = OpenSSL::HMAC.new('key', 'SHA1')
#=> f42bb0eeb018ebbd4597ae7213711ec60760843f

instance.update(data)
#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9
instance.reset
#=> f42bb0eeb018ebbd4597ae7213711ec60760843f

to_s

Псевдоним для: hexdigest

update(string) → self

Исходный код

static VALUE
ossl_hmac_update(VALUE self, VALUE data)
{
    EVP_MD_CTX *ctx;

    StringValue(data);
    GetHMAC(self, ctx);
    if (EVP_DigestSignUpdate(ctx, RSTRING_PTR(data), RSTRING_LEN(data)) != 1)
        ossl_raise(eHMACError, "EVP_DigestSignUpdate");

    return self;
}

Возвращает hmac, обновлённый сообщением, подлежащим аутентификации. Может вызываться многократно с частями сообщения.

Пример

first_chunk = 'The quick brown fox jumps '
second_chunk = 'over the lazy dog'

instance.update(first_chunk)
#=> 5b9a8038a65d571076d97fe783989e52278a492a
instance.update(second_chunk)
#=> de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9

Также псевдоним для: <<

Ruby Core © 1993–2024 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.