class OpenSSL::Cipher (Ruby 2.7.0 リファレンスマニュアル)

要約

共通鍵暗号のために抽象化されたインターフェースを提供するクラスです。

基本的にこのクラスを直接使ってデータを暗号化することは避けてください。通常はより高水準なインターフェースが利用可能なはずです。必要なのは暗号アルゴリズムを指定するため OpenSSL::Cipher.new で暗号オブジェクトを生成することだけでしょう。

もし、このクラスを直接利用して暗号化する場合は、暗号の鍵や IV(Initialization Vector)の取り扱いについて正しく理解してからにしてください。

以下の手順で利用します。

OpenSSL::Cipher.new や OpenSSL::Cipher::AES256.new などで暗号オブジェクトを生成する
OpenSSL::Cipher#encrypt, OpenSSL::Cipher#decrypt で暗号、復号のいずれをするかを設定する
OpenSSL::Cipher#key=, OpenSSL::Cipher#iv=, OpenSSL::Cipher#random_key, OpenSSL::Cipher#random_iv などで鍵と IV(initialization vector) を設定する
OpenSSL::Cipher#update, OpenSSL::Cipher#final で暗号化/復号化をする

ruby 1.8.3 から Cast5 と Idea が CAST5 と IDEA に改名されました。

ブロック暗号モード

AES のようなブロック暗号では暗号方式を選択する際にモードを指定する必要があります。このライブラリでは以下のような文字列でモードを指定できます。

"CBC"
"CFB"
"ECB"
"OFB"

これらの文字列の意味は openssl/参考文献などで調べてください。 AES を用いる場合、通常は CBC を用いれば良いでしょう。選択肢によっては安全性に問題があるので気をつけてください。

使用例

require 'openssl'

# 暗号化するデータ
data = "*secret data*"
# パスワード
pass = "**secret password**"
# salt
salt = OpenSSL::Random.random_bytes(8)

# 暗号化器を作成する
enc = OpenSSL::Cipher.new("AES-256-CBC")
enc.encrypt
# 鍵とIV(Initialize Vector)を PKCS#5 に従ってパスワードと salt から生成する
key_iv = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, 2000, enc.key_len + enc.iv_len)
key = key_iv[0, enc.key_len]
iv = key_iv[enc.key_len, enc.iv_len]
# 鍵とIVを設定する
enc.key = key
enc.iv = iv

# 暗号化する
encrypted_data = ""
encrypted_data << enc.update(data)
encrypted_data << enc.final

p encrypted_data

# 復号化器を作成する
dec = OpenSSL::Cipher.new("AES-256-CBC")
dec.decrypt

# 鍵とIVを設定する
dec.key = key
dec.iv = iv

# 復号化する
decrypted_data = ""
decrypted_data << dec.update(encrypted_data)
decrypted_data << dec.final

p decrypted_data

特異メソッド

ciphers -> [String][permalink][rdoc][edit]

利用可能な暗号方式名を文字列の配列で返します。

require 'openssl'

OpenSSL::Cipher.ciphers
# => ["AES-128-CBC", "AES-128-CFB", "AES-128-CFB1", "AES-128-CFB8", "AES-128-ECB", "AES-128-OFB", "AES-192-CBC", ... ]

new(name) -> OpenSSL::Cipher[permalink][rdoc][edit]

共通鍵暗号のアルゴリズム名を渡し、対応する暗号オブジェクトを生成します。

利用できるアルゴリズムはシステムにインストールされている openssl に依存します。 OpenSSL::Cipher.ciphers で利用可能な暗号のアルゴリズム名が得られます。

さまざまな方式がありますが、2006年現在 aes256 (aes-256-cbc) を用いるのが安心でしょう。

[PARAM] name:: 暗号化方式の名前
[EXCEPTION] RuntimeError:: 利用可能でない暗号化方式名を指定した場合に発生します
[EXCEPTION] OpenSSL::Cipher::CipherError:: 初期化に失敗した場合に発生します

インスタンスメソッド

block_size -> Integer[permalink][rdoc][edit]

暗号化のブロックのサイズをバイト数で返します。

decrypt(pass, iv = nil) -> self[permalink][rdoc][edit]

復号化の準備をします。

暗号オブジェクトの内部状態を復号化のために初期化します。

pass と iv が渡された場合、これらを用いて鍵を生成し、暗号オブジェクトに鍵と IV を設定します。このやりかたは非標準的であるため利用すべきではありません。

[PARAM] pass:: パスワード文字列
[PARAM] iv:: IV文字列
[EXCEPTION] OpenSSL::Cipher::CipherError:: 準備に失敗した場合に発生します

encrypt -> self[permalink][rdoc][edit]

encrypt(pass, iv = nil) -> self

暗号化の準備をします。

暗号オブジェクトの内部状態を暗号化のために初期化します。

[PARAM] pass:: パスワード文字列
[PARAM] iv:: IV文字列
[EXCEPTION] OpenSSL::Cipher::CipherError:: 準備に失敗した場合に発生します

final -> String[permalink][rdoc][edit]

暗号オブジェクト内部に残されたデータを暗号化/復号化し、文字列で返します。

パディング(OpenSSL::Cipher#padding=)を有効にしている場合は、残されたデータにパディングを付加した上で暗号化します。

iv=(iv)[permalink][rdoc][edit]

IV(Initialization Vector) を設定します。

[PARAM] iv:: IV文字列

iv_len -> Integer[permalink][rdoc][edit]

必要な IV(Initialization Vector) の長さをバイト数で返します。

key=(key)[permalink][rdoc][edit]

暗号鍵を設定します。

なお、ここでいう「暗号鍵」は各暗号アルゴリズムに渡される鍵であって、「パスワード」ではありません。

key_len -> Integer[permalink][rdoc][edit]

暗号鍵の長さをバイト数で返します。

key_len=(length)[permalink][rdoc][edit]

暗号鍵の長さを変更します。

[PARAM] length:: 新しく設定する長さ(バイト数)
[EXCEPTION] OpenSSL::Cipher::CipherError:: 指定した長さが不適切である(暗号方式の規格上許されていない値である)場合に発生します

name -> String[permalink][rdoc][edit]

暗号化アルゴリズムの名前を文字列で返します。

padding=(padding)[permalink][rdoc][edit]

パディングを設定します。

1 でパディングを有効に、0で無効にします。

パディングを無効化した場合には、暗号化するデータのサイズはブロックサイズの倍数でなければなりません。

暗号化する側と復号化する側でパディングの設定を一致させておかなければなりません。

[PARAM] padding:: 1でパディングを有効、0で無効
[EXCEPTION] OpenSSL::Cipher::CipherError:: 設定に失敗した場合に発生します

pkcs5_keyivgen(pass, salt=nil, num=2048, digest="md5") -> nil[permalink][rdoc][edit]

pass と salt から鍵と IV を生成し、暗号オブジェクトに設定します。

このメソッドは PKCS#5 v1.5 で定義されている方法に従って鍵と IV を生成します。PKCS#5 v1.5 と正しく互換するには digest は md5 か sha1 を使い、暗号アルゴリズムは RC2, RC4-40, DES のいずれかを使わなければなりません。

このメソッドの利用は推奨されません。これではなく PKCS#5 v2.0 に定義されている方法で鍵と IV を生成すべきです。

salt が nil である場合には salt なしと見なします。

num は必要なデータの生成でハッシュ関数を何回繰り返し適用するかを指定します。最低でも1000を使うべきです。

[PARAM] pass:: パスワード文字列
[PARAM] salt:: 鍵と IV を生成するための salt 文字列、長さは 8 byte でなければならない
[PARAM] num:: ハッシュ関数の適用回数
[PARAM] digest:: ハッシュアルゴリズムを指定する文字列もしくは OpenSSL::Digest のオブジェクト
[EXCEPTION] OpenSSL::Cipher::CipherError:: saltが8 byte でない場合や、鍵と IV の設定に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKCS5

random_iv -> String[permalink][rdoc][edit]

IV を乱数で生成し、暗号オブジェクトに設定します。

生成した IV を文字列で返します。

random_key -> String[permalink][rdoc][edit]

鍵を乱数で生成し、暗号オブジェクトに設定します。

生成した鍵を文字列で返します。

reset -> self[permalink][rdoc][edit]

内部状態をリセットします。

鍵、IV、暗号化/復号化待ちデータなどがクリアされます。

update(data) -> String[permalink][rdoc][edit]

渡された文字列を暗号化もしくは復号化して文字列として返します。

どちらがなされるかは直前に OpenSSL::Cipher#encrypt もしくは OpenSSL::Cipher#decrypt のいずれが呼びだされたかによって決まります。

ブロック暗号を利用する場合は、暗号化/復号化はブロックサイズで規定されたバイト数ごとに行われます。そのため余ったデータは暗号オブジェクト内部に保存され、次の文字列が渡されたときに使われます。

暗号化/復号化すべきデータを渡し終えた後は、 OpenSSL::Cipher#final を呼びだして暗号オブジェクト内部に残されたデータを暗号化/復号化する必要があります。

[PARAM] data:: 暗号化/復号化する文字列

要約

ブロック暗号モード

使用例

目次

特異メソッド

インスタンスメソッド