opensecret 0.0.9925 → 0.0.9949

data/lib/keytools/doc.rsa.radix.binary-mapping.ruby

@@ -1,190 +0,0 @@
-
-For Starters....
-I am often torn when programming between using libraries and following the DIY approach. On one hand you can accomplish a lot in a short time by including libraries that have the functionality you need and just bridging the gaps, but I am often left with the feeling of some loss-of-control and bloat. Obviously some library usage is inevitable, but I do like to take a minimalist approach to including external libraries because the management burden of updating libraries, the effort to make various libraries play together and because moving library-heavy applications between platforms can be... interesting. Most of all I like the learning that takes place when building it yourself. It was for this reason that I decided to see if I could effectively utilize the OpenSSL library that is typically part of a Ruby installation to create my own higher-level encryption/decryption class. Before we dive in I would like to layout the details of the application.
-
-Password Management App
-
-I have for years maintained a PGP encrypted file for my account passwords. I had the desire to centralize this and make it more web accessible. In order to do this I wanted assurance that the data was not only encrypted on the wire via SSL, but also at rest. I looked at various Ruby PGP/GPG libraries, but all of the ones I surveyed were wrappers around the GPG binary itself which didn't make it very web host friendly ( I planned on hosting it on Heroku with a Couchdb backend on Cloudant). That was when I decided to look at OpenSSL for file encryption since it is typically part of a Ruby installation and was available on Heroku. I also had the need for public-key encryption so a password store could be shared between two or more people (I share some accounts with my partner).
-
-Take One... RSA
-I thought I could simply use RSA encryption to meet all my needs and at first it worked quite well. Creating keys was straight forward and encryption/decryption worked well. One caveat is that the string passed to the FileEncryptor#encrypt_string method cannot be larger than the key size + PKCS padding size (11 bytes). So for a 128 byte (1024 bit) key the string should only be 117 bytes (see String#size).
-
-
-require 'openssl'
-
-class Encryptor
-  
-  def initialize(key_pass, key_size = 1024, key_name = 'rsakey.sec', cipher = OpenSSL::Cipher.new('aes-256-cbc'))
-    @key_size = key_size
-    @cipher = cipher
-    @key_name = key_name
-
-    if( File.exists?(@key_name) )
-      @rsakey = OpenSSL::PKey::RSA.new(File.read(@key_name), key_pass)
-    else
-      @rsakey = OpenSSL::PKey::RSA.generate(@key_size)
-      File.open(@key_name,'w+') do |priv|
-        priv.write(@rsakey.to_pem(@cipher, key_pass))
-      end
-    end
-  end
-
-  def encrypt_string(txt)
-    begin
-      @rsakey.public_encrypt(txt)
-    rescue OpenSSL::PKey::RSAError => e
-      if e.message == 'data too large for key size'
-        STDERR.puts 'Your string is too large to encrypt'
-      else
-        raise
-      end
-    end
-  end
-
-  def decrypt_string(etxt)
-    @rsakey.private_decrypt(etxt)
-  end
-end
-
-
-
-
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-## -- See YAML storage of key (excellent).
-
-
-
-This seemed to work quite well until I remembered that I needed to have the encrypted data be readable by multiple parties. I then had to change my approach and decided to use a symmetric AES key that is then shared between the multiple parties and each person encrypts the key with their RSA public key.
-
-Take Two... RSA + AES
-In order to accomplish secure use of the AES key we start out the same way as the previous solution by creating a RSA key. It will only be used to secure AES keys that we use to protect certain data stores. So if I have a data store I want to share with my brother I encrypt the data store with an AES key then I encrypt that key with my public RSA key and my brother's public RSA key. Now both he and I can access anything in that store and the AES key is still secure from prying eyes. Here is an overview of the steps taken before I post the code.
-Create a RSA key-pair
-Create an AES key to encrypt the data store
-Encrypt the AES key with your RSA public key
-To give access to the data store encrypt the AES key with the person's public RSA key send them back the cipher-text.
-
-And here is the class I wrote to make this work:
-
-
-require 'openssl'
-require 'yaml'
-
-class Encryptor
-  
-  def initialize(key_pass, key_size = 2048, key_name = 'rsakey.sec', cipher = OpenSSL::Cipher.new('aes-256-cbc'))
-    @key_size = key_size
-    @cipher = cipher
-    @key_name = key_name
-
-    if( File.exists?(@key_name) )
-      @rsakey = OpenSSL::PKey::RSA.new(File.read(@key_name), key_pass)
-    else
-      @rsakey = OpenSSL::PKey::RSA.generate(@key_size)
-      File.open(@key_name,'w+') do |priv|
-        priv.write(@rsakey.to_pem(@cipher, key_pass))
-      end
-    end
-  end
-
-  def rsa_encrypt(txt, pub_key=nil)
-    begin
-      pub_key.nil? ? @rsakey.public_encrypt(txt) : OpenSSL::PKey::RSA.new(pub_key).public_encrypt(txt)
-    rescue OpenSSL::PKey::RSAError => e
-      if e.message == 'data too large for key size'
-        STDERR.puts 'Your string is too large to encrypt'
-      else
-        raise
-      end
-    end
-  end
-
-  def rsa_decrypt(etxt)
-    @rsakey.private_decrypt(etxt)
-  end
-
-  def aes_encrypt(txt, aes_file)
-    key = get_aes_key(aes_file)
-    cif = OpenSSL::Cipher.new('AES-256-CBC')
-    cif.encrypt
-    cif.key = key[:key]
-    cif.iv  = key[:iv] = cif.random_iv
-    save_aes_key(aes_file, key)
-    etxt = ''
-    etxt << cif.update(txt)
-    etxt << cif.final
-    etxt
-  end
-
-  def aes_decrypt(etxt, aes_file)
-    key = get_aes_key(aes_file)
-    cif = OpenSSL::Cipher.new('AES-256-CBC')
-    cif.decrypt
-    cif.key = key[:key]
-    cif.iv  = key[:iv]
-    txt = ''
-    txt << cif.update(etxt)
-    txt << cif.final
-    txt
-  end
-
-  def gen_aes_key(file)
-    cif = OpenSSL::Cipher.new('AES-256-CBC')
-    key = {key: cif.random_key}
-    save_aes_key(file, key)
-    key
-  end
-
-  def save_aes_key(file,key_iv) 
-    File.open(file,'w+') do |f|
-      f.write(rsa_encrypt(YAML.dump(key_iv)))
-    end
-  end
-
-  def get_aes_key(file)
-    YAML.load(rsa_decrypt(File.read(file)))
-  end
-  
-  def give_aes_key(aes_file, rsa_pub)
-    aes = get_aes_key(aes_file)
-    rsa_encrypt(YAML.dump(aes), rsa_pub)
-  end
-
-end
-
-
-
-Below is a demonstration of the use of this class to accomplish the needs I had for my password protector application. I am aware that this class needs some refactoring and it's a bit annoying to have to pass the AES key file to the methods, but logically it is working the way I had hoped.
-
-
-
-fe = Encryptor.new('mysecret')
-
-aesfile = 'aeskey.sec'
-
-fe.gen_aes_key(aesfile)
-
-etxt = fe.aes_encrypt('this is a test', aesfile)
-
-txt = fe.aes_decrypt(etxt, aesfile)
-
-pub_key = < Assume I got someone's public RSA Key somehow >
-
-fe.give_aes_key(aesfile, pub_key)
-
-Like I mentioned, this code needs to be cleaned up a bit, but it gives me all of the functionality I need to build my application and it doesn't require any external libraries except OpenSSL and YAML which are typically standard in any Ruby installation.
-
-Hopefully someone finds this post useful and if you have any additions, corrections, criticisms please post them below. Feedback is always welcome.

data/lib/keytools/doc.star.schema.strategy.txt

@@ -1,77 +0,0 @@
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Star Schema Strategy
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
- - We move away from a single private key to one per sealed envelope.
-
-There are 2 huge 72 character keys ( NOT base64 characters but UTF-7 (or 8) possible characters )
-
-   (note - in common mistakes article put the fact that random keys are generated
-           from tools like securerandom that do not cover the full range f possible
-	   chars hence sharpely narrowing the search space for an attacker.
-	   )
-
-   Write test program to prove that EVERY ONE of THE 128 CHARACTERS COUNT.
-   How ----> Create 71 characters that are all AAAAAAA...
-       ====> Rotate round each of the 128 chars as the 72nd character
-       ----> Check that bcrypt generates 128 different outcomes for each of the 128 chars.
-
-
-==> Use get random bytes to get 72 random bytes (not secure random which halves (if not worse) the search space).
-
-
-When password entered we read the salt and retrieve the key and unlock the STRONG 256 BIT key (found by getting 32 random bytes then mapping to 32 bytes with say SHA512 digest) crypt for index file.
-
-We then grab this crypt key (32 bytes long or 64 bytes - the longest a symmetric crypt key can be) - test this out with AES256.
-
-The crypt key unlocks the index file.
-
-We then grab the session ID - then hash that say through Digest.SHA512 - and use the resulting key to decrypt the ENVironment VARIABLE.
-This reveals a 512 (or 256) bit SESSION crypt key which creates a copy of the (in-memory) index file and then writes it with a new name
-that is the alpha-number session ID hash. We encrypt the index file with the new key.
-
-Still in SAME CALL we prepare the NEXT (future) SEAL password. We create a 256 bit key and then derive a new bcrypt salt and out comes the 186bit key (which we hash and use to lock the 256 bit key just created and we save the salt in the configs and save the future SEAL password crypt in the configs.
-The crux move is we use the session key to also lock the seal password for when session ends.
-
-NOW WE THROW AWAY THE PASSWORD THE BEAUTY OF THIS METHOD IS THAT WE NEVER KEEP THE PASSWORD ANYWHERE ENCRYPTED OR OTHERWISE - WE TRHOW IT AWAY WE WONT NEED IT AGAIN UNTIL THE NEXT SESSION.
-
-
-Now we continue with the other open, put, add type calls. They all now accesses the copied session index file and it is changed as appropriate.
-
-
-Finally when the SEAL time comes we use session key to unlock and retrieve the NEXT time (seal) key. We lock index file with this key.
-
-In clean up we throw away all our session bits and bobs.
-
-
-We are ready for "next time" - when the password is entered we derive the key again and can unlock the last saved index file!! Cool plan or what??
-
-
-REDIS Store + more
-
-This plan allows a seamless migration to keeping the index not in a file (risks failure)
-but in a REDIS or etcd or PostgreSQL or other key-value stores.
-
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Star Schema for Each Envelope Details
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
- - path off session base
- - path to private key
- - (inner encrypted private key lock)
- - path to keyfile
- - path to crypt file
- - outer path
- - inner path
- - sealed already?
- - is reopen or no?
- - last accessed time
- - who by user@hostname
- - on what ppi (shell) id@mac address
- - top level count
-
-

data/lib/keytools/doc.using.pbkdf2.kdf.ruby

@@ -1,95 +0,0 @@
-# coding: utf-8
-
-    # OpenSSL::PKCS5.pbkdf2_hmac has been renamed to OpenSSL::KDF.pbkdf2_hmac.
-    # This method is provided for backwards compatibility.
-
-    def pbkdf2_hmac(pass, salt, iter, keylen, digest)
-
-      OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
-                               length: keylen, hash: digest)
-
-    end
-
-
-##########################################################################################
-##########################################################################################
-##########################################################################################
-##########################################################################################
-##########################################################################################
-
-
-OpenSSL::KDF
-Provides functionality of various KDFs (key derivation function).
-
-KDF is typically used for securely deriving arbitrary length symmetric keys to be used with an OpenSSL::Cipher from passwords. Another use case is for storing passwords: Due to the ability to tweak the effort of computation by increasing the iteration count, computation can be slowed down artificially in order to render possible attacks infeasible.
-
-Currently, OpenSSL::KDF provides implementations for the following KDF:
-
-PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination with HMAC
-
-scrypt
-
-HKDF
-
-############################
-#### Parameters
-############################
-
-pass = the passphrase
-
-salt = The salt. Salts prevent attacks based on dictionaries of common passwords and attacks based on rainbow tables. It is a public value that can be safely stored along with the password (e.g. if the derived value is used for password storage).
-
-iterations = The iteration count. This provides the ability to tune the algorithm. It is better to use the highest count possible for the maximum resistance to brute-force attacks.
-
-length = The desired length of the derived key in octets.
-
-hash = The hash algorithm used with HMAC for the PRF. May be a String representing the algorithm name, or an instance of OpenSSL::Digest.
-
-
-############################
-#### Examples
-############################
-
-Generating a 128 bit key for a Cipher (e.g. AES)¶ ↑
-pass = "secret"
-salt = OpenSSL::Random.random_bytes(16)
-iter = 20_000
-key_len = 16
-key = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
-                               length: key_len, hash: "sha1")
-
-############################
-#### Storing Passwords
-############################
-
-pass = "secret"
-# store this with the generated value
-salt = OpenSSL::Random.random_bytes(16)
-iter = 20_000
-hash = OpenSSL::Digest::SHA256.new
-len = hash.digest_length
-# the final value to be stored
-value = OpenSSL::KDF.pbkdf2_hmac(pass, salt: salt, iterations: iter,
-                                 length: len, hash: hash)
-
-############################
-#### Important Note on Checking Passwords
-#### Thwart Timing Attacks by taking the Same Amount of Time to Check Failures and Successes
-############################
-
-When comparing passwords provided by the user with previously stored values, a common mistake made is comparing the two values using "==". Typically, "==" short-circuits on evaluation, and is therefore vulnerable to timing attacks. The proper way is to use a method that always takes the same amount of time when comparing two values, thus not leaking any information to potential attackers. To compare two values, the following could be used:
-
-def eql_time_cmp(a, b)
-  unless a.length == b.length
-    return false
-  end
-  cmp = b.bytes
-  result = 0
-  a.bytes.each_with_index {|c,i|
-    result |= c ^ cmp[i]
-  }
-  result == 0
-end
-                           Please note that the premature return in case of differing lengths typically does not leak valuable information - when using PBKDF2, the length of the values to be compared is of fixed size.
-
-                                                                                                                                                                                                                     

data/lib/keytools/doc.using.pbkdf2.pkcs.ruby

@@ -1,266 +0,0 @@
-# coding: utf-8
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Creating a Key
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-This example creates a 2048 bit RSA keypair and writes it to the current directory.
-
-key = OpenSSL::PKey::RSA.new 2048
-
-open 'private_key.pem', 'w' do |io| io.write key.to_pem end
-open 'public_key.pem', 'w' do |io| io.write key.public_key.to_pem end
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Exporting a Key
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-Keys saved to disk without encryption are not secure as anyone who gets ahold of the key may use it unless it is encrypted. In order to securely export a key you may export it with a pass phrase.
-
-cipher = OpenSSL::Cipher.new 'AES-128-CBC'
-pass_phrase = 'my secure pass phrase goes here'
-
-key_secure = key.export cipher, pass_phrase
-
-open 'private.secure.pem', 'w' do |io|
-  io.write key_secure
-end
-OpenSSL::Cipher.ciphers returns a list of available ciphers.
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Loading a Key
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-A key can also be loaded from a file.
-
-key2 = OpenSSL::PKey::RSA.new File.read 'private_key.pem'
-key2.public? # => true
-key2.private? # => true
-or
-
-key3 = OpenSSL::PKey::RSA.new File.read 'public_key.pem'
-key3.public? # => true
-key3.private? # => false
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Loading an Encrypted Key
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-OpenSSL will prompt you for your pass phrase when loading an encrypted key. If you will not be able to type in the pass phrase you may provide it when loading the key:
-
-key4_pem = File.read 'private.secure.pem'
-pass_phrase = 'my secure pass phrase goes here'
-key4 = OpenSSL::PKey::RSA.new key4_pem, pass_phrase
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### RSA Encryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-RSA provides encryption and decryption using the public and private keys. You can use a variety of padding methods depending upon the intended use of encrypted data.
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Encryption & Decryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-Asymmetric public/private key encryption is slow and victim to attack in cases where it is used without padding or directly to encrypt larger chunks of data. Typical use cases for RSA encryption involve wrapping a symmetric key with the public key of the recipient who would unwrap that symmetric key again using their private key. The following illustrates a simplified example of such a key transport scheme. It shouldnt be used in practice, though, standardized protocols should always be preferred.
-
-wrapped_key = key.public_encrypt key
-A symmetric key encrypted with the public key can only be decrypted with the corresponding private key of the recipient.
-
-original_key = key.private_decrypt wrapped_key
-By default PKCS#1 padding will be used, but it is also possible to use other forms of padding, see PKey::RSA for further details.
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Signatures
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-
-Using “private_encrypt” to encrypt some data with the private key is equivalent to applying a digital signature to the data. A verifying party may validate the signature by comparing the result of decrypting the signature with “public_decrypt” to the original data. However, OpenSSL::PKey already has methods “sign” and “verify” that handle digital signatures in a standardized way - “private_encrypt” and “public_decrypt” shouldnt be used in practice.
-
-To sign a document, a cryptographically secure hash of the document is computed first, which is then signed using the private key.
-
-digest = OpenSSL::Digest::SHA256.new
-signature = key.sign digest, document
-To validate the signature, again a hash of the document is computed and the signature is decrypted using the public key. The result is then compared to the hash just computed, if they are equal the signature was valid.
-
-digest = OpenSSL::Digest::SHA256.new
-if key.verify digest, signature, document
-  puts 'Valid'
-else
-  puts 'Invalid'
-end
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### PBKDF2 Password-based Encryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-If supported by the underlying OpenSSL version used, Password-based Encryption should use the features of PKCS5. If not supported or if required by legacy applications, the older, less secure methods specified in RFC 2898 are also supported (see below).
-
-PKCS5 supports PBKDF2 as it was specified in PKCS#5 v2.0. It still uses a password, a salt, and additionally a number of iterations that will slow the key derivation process down. The slower this is, the more work it requires being able to brute-force the resulting key.
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Encryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-The strategy is to first instantiate a Cipher for encryption, and then to generate a random IV plus a key derived from the password using PBKDF2. PKCS #5 v2.0 recommends at least 8 bytes for the salt, the number of iterations largely depends on the hardware being used.
-
-cipher = OpenSSL::Cipher.new 'AES-128-CBC'
-cipher.encrypt
-iv = cipher.random_iv
-
-pwd = 'some hopefully not to easily guessable password'
-salt = OpenSSL::Random.random_bytes 16
-iter = 20000
-key_len = cipher.key_len
-digest = OpenSSL::Digest::SHA256.new
-
-key = OpenSSL::PKCS5.pbkdf2_hmac(pwd, salt, iter, key_len, digest)
-cipher.key = key
-
-Now encrypt the data:
-
-encrypted = cipher.update document
-encrypted << cipher.final
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Decryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-Use the same steps as before to derive the symmetric AES key, this time setting the Cipher up for decryption.
-
-cipher = OpenSSL::Cipher.new 'AES-128-CBC'
-cipher.decrypt
-cipher.iv = iv # the one generated with #random_iv
-
-pwd = 'some hopefully not to easily guessable password'
-salt = ... # the one generated above
-iter = 20000
-key_len = cipher.key_len
-digest = OpenSSL::Digest::SHA256.new
-
-key = OpenSSL::PKCS5.pbkdf2_hmac(pwd, salt, iter, key_len, digest)
-cipher.key = key
-
-Now decrypt the data:
-
-decrypted = cipher.update encrypted
-decrypted << cipher.final
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### PKCS #5 Password-based Encryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-PKCS #5 is a password-based encryption standard documented at RFC2898. It allows a short password or passphrase to be used to create a secure encryption key. If possible, PBKDF2 as described above should be used if the circumstances allow it.
-
-PKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption key.
-
-pass_phrase = 'my secure pass phrase goes here'
-salt = '8 octets'
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Encryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-First set up the cipher for encryption
-
-encryptor = OpenSSL::Cipher.new 'AES-128-CBC'
-encryptor.encrypt
-encryptor.pkcs5_keyivgen pass_phrase, salt
-Then pass the data you want to encrypt through
-
-encrypted = encryptor.update 'top secret document'
-encrypted << encryptor.final
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Decryption
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-Use a new Cipher instance set up for decryption
-
-decryptor = OpenSSL::Cipher.new 'AES-128-CBC'
-decryptor.decrypt
-decryptor.pkcs5_keyivgen pass_phrase, salt
-Then pass the data you want to decrypt through
-
-plain = decryptor.update encrypted
-plain << decryptor.final
-
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@ ### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### OpenSSL::PKCS5
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-Provides password-based encryption functionality based on PKCS#5. Typically used for securely deriving arbitrary length symmetric keys to be used with an OpenSSL::Cipher from passwords. Another use case is for storing passwords: Due to the ability to tweak the effort of computation by increasing the iteration count, computation can be slowed down artificially in order to render possible attacks infeasible.
-
-PKCS5 offers support for PBKDF2 with an OpenSSL::Digest::SHA1-based HMAC, or an arbitrary Digest if the underlying version of OpenSSL already supports it (>= 0.9.4).
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Parameters
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-
-1 - Password - Typically an arbitrary String that represents the password to be used for deriving a key.
-
-2 - Salt - Prevents attacks based on dictionaries of common passwords. It is a public value that can be safely stored along with the password (e.g. if PBKDF2 is used for password storage). For maximum security, a fresh, random salt should be generated for each stored password. According to PKCS#5, a salt should be at least 8 bytes long.
-
-3 - Iteration Count - Allows to tweak the length that the actual computation will take. The larger the iteration count, the longer it will take.
-
-4 - Key Length - Specifies the length in bytes of the output that will be generated. Typically, the key length should be larger than or equal to the output length of the underlying digest function, otherwise an attacker could simply try to brute-force the key. According to PKCS#5, security is limited by the output length of the underlying digest function, i.e. security is not improved if a key length strictly larger than the digest output length is chosen. Therefore, when using PKCS5 for password storage, it suffices to store values equal to the digest output length, nothing is gained by storing larger values.
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Generating a 128 bit key for a Cipher (e.g. AES)
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-pass = "secret"
-salt = OpenSSL::Random.random_bytes(16)
-iter = 20000
-key_len = 16
-key = OpenSSL::PKCS5.pbkdf2_hmac_sha1(pass, salt, iter, key_len)
-
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-### Storing Passwords
-### @@@@@@@@@@@@@@@@@@@@@@@@@@
-
-pass = "secret"
-salt = OpenSSL::Random.random_bytes(16) #store this with the generated value
-iter = 20000
-digest = OpenSSL::Digest::SHA256.new
-len = digest.digest_length
-#the final value to be stored
-value = OpenSSL::PKCS5.pbkdf2_hmac(pass, salt, iter, len, digest)
-Important Note on Checking Passwords¶ ↑
-When comparing passwords provided by the user with previously stored values, a common mistake made is comparing the two values using "==". Typically, "==" short-circuits on evaluation, and is therefore vulnerable to timing attacks. The proper way is to use a method that always takes the same amount of time when comparing two values, thus not leaking any information to potential attackers. To compare two values, the following could be used:
-
-def eql_time_cmp(a, b)
-  unless a.length == b.length
-    return false
-  end
-  cmp = b.bytes.to_a
-  result = 0
-  a.bytes.each_with_index {|c,i|
-    result |= c ^ cmp[i]
-  }
-  result == 0
-end
-
-
-Please note that the premature return in case of differing lengths typically does not leak valuable information - when using PKCS#5, the length of the values to be compared is of fixed size.