U:RDoc::NormalModule[iI" OpenSSL:EF@0o:RDoc::Markup::Document: @parts[&o;;[: @fileI""ext/openssl/lib/openssl/bn.rb;T:0@omit_headings_from_table_of_contents_below0o;;[; I"&ext/openssl/lib/openssl/cipher.rb;T; 0o;;[; I"&ext/openssl/lib/openssl/config.rb;T; 0o;;[; I"&ext/openssl/lib/openssl/digest.rb;T; 0o;;[; I"$ext/openssl/lib/openssl/pkey.rb;T; 0o;;[; I"#ext/openssl/lib/openssl/ssl.rb;T; 0o;;[; I"$ext/openssl/lib/openssl/x509.rb;T; 0o;;[o:RDoc::Markup::Paragraph;[I"OOpenSSL provides SSL, TLS and general purpose cryptography. It wraps the ;TI".OpenSSL[http://www.openssl.org/] library.;To:RDoc::Markup::BlankLineS:RDoc::Markup::Heading: leveli: textI" Examples;T@%o; ;[I"6All examples assume you have loaded OpenSSL with:;T@%o:RDoc::Markup::Verbatim;[I"require 'openssl' ;T: @format0o; ;[I"OThese examples build atop each other. For example the key created in the ;TI"/next is used in throughout these examples.;T@%S; ;i;I" Keys;T@%S; ;i;I"Creating a Key;T@%o; ;[I"NThis example creates a 2048 bit RSA keypair and writes it to the current ;TI"directory.;T@%o;;[ I"'key = OpenSSL::PKey::RSA.new 2048 ;TI" ;TI"Aopen 'private_key.pem', 'w' do |io| io.write key.to_pem end ;TI"Kopen 'public_key.pem', 'w' do |io| io.write key.public_key.to_pem end ;T;0S; ;i;I"Exporting a Key;T@%o; ;[I"MKeys saved to disk without encryption are not secure as anyone who gets ;TI"Oahold of the key may use it unless it is encrypted. In order to securely ;TI"7export a key you may export it with a pass phrase.;T@%o;;[ I"0cipher = OpenSSL::Cipher.new 'AES-128-CBC' ;TI"5pass_phrase = 'my secure pass phrase goes here' ;TI" ;TI"1key_secure = key.export cipher, pass_phrase ;TI" ;TI",open 'private.secure.pem', 'w' do |io| ;TI" io.write key_secure ;TI" end ;T;0o; ;[I"AOpenSSL::Cipher.ciphers returns a list of available ciphers.;T@%S; ;i;I"Loading a Key;T@%o; ;[I"*A key can also be loaded from a file.;T@%o;;[I"?key2 = OpenSSL::PKey::RSA.new File.read 'private_key.pem' ;TI"key2.public? # => true ;TI"key2.private? # => true ;T;0o; ;[I"or;T@%o;;[I">key3 = OpenSSL::PKey::RSA.new File.read 'public_key.pem' ;TI"key3.public? # => true ;TI"key3.private? # => false ;T;0S; ;i;I"Loading an Encrypted Key;T@%o; ;[I"QOpenSSL will prompt you for your pass phrase when loading an encrypted key. ;TI"PIf you will not be able to type in the pass phrase you may provide it when ;TI"loading the key:;T@%o;;[I"/key4_pem = File.read 'private.secure.pem' ;TI"5pass_phrase = 'my secure pass phrase goes here' ;TI"9key4 = OpenSSL::PKey::RSA.new key4_pem, pass_phrase ;T;0S; ;i;I"RSA Encryption;T@%o; ;[I"ORSA provides encryption and decryption using the public and private keys. ;TI"QYou can use a variety of padding methods depending upon the intended use of ;TI"encrypted data.;T@%S; ;i;I"Encryption & Decryption;T@%o; ;[ I"NAsymmetric public/private key encryption is slow and victim to attack in ;TI"Qcases where it is used without padding or directly to encrypt larger chunks ;TI"Rof data. Typical use cases for RSA encryption involve "wrapping" a symmetric ;TI"Pkey with the public key of the recipient who would "unwrap" that symmetric ;TI"(key again using their private key. ;TI"LThe following illustrates a simplified example of such a key transport ;TI"Nscheme. It shouldn't be used in practice, though, standardized protocols ;TI" should always be preferred.;T@%o;;[I"*wrapped_key = key.public_encrypt key ;T;0o; ;[I"NA symmetric key encrypted with the public key can only be decrypted with ;TI"4the corresponding private key of the recipient.;T@%o;;[I"4original_key = key.private_decrypt wrapped_key ;T;0o; ;[I"LBy default PKCS#1 padding will be used, but it is also possible to use ;TI"?other forms of padding, see PKey::RSA for further details.;T@%S; ;i;I"Signatures;T@%o; ;[ I"JUsing "private_encrypt" to encrypt some data with the private key is ;TI"Iequivalent to applying a digital signature to the data. A verifying ;TI"Lparty may validate the signature by comparing the result of decrypting ;TI"Hthe signature with "public_decrypt" to the original data. However, ;TI"GOpenSSL::PKey already has methods "sign" and "verify" that handle ;TI"Fdigital signatures in a standardized way - "private_encrypt" and ;TI"4"public_decrypt" shouldn't be used in practice.;T@%o; ;[I"LTo sign a document, a cryptographically secure hash of the document is ;TI"@computed first, which is then signed using the private key.;T@%o;;[I"*digest = OpenSSL::Digest::SHA256.new ;TI"+signature = key.sign digest, document ;T;0o; ;[ I"MTo validate the signature, again a hash of the document is computed and ;TI"Ithe signature is decrypted using the public key. The result is then ;TI"Mcompared to the hash just computed, if they are equal the signature was ;TI" valid.;T@%o;;[ I"*digest = OpenSSL::Digest::SHA256.new ;TI"/if key.verify digest, signature, document ;TI" puts 'Valid' ;TI" else ;TI" puts 'Invalid' ;TI" end ;T;0S; ;i;I"%PBKDF2 Password-based Encryption;T@%o; ;[ I"IIf supported by the underlying OpenSSL version used, Password-based ;TI"IEncryption should use the features of PKCS5. If not supported or if ;TI"Orequired by legacy applications, the older, less secure methods specified ;TI"0in RFC 2898 are also supported (see below).;T@%o; ;[ I"9PKCS5 supports PBKDF2 as it was specified in PKCS#5 ;TI"Hv2.0[http://www.rsa.com/rsalabs/node.asp?id=2127]. It still uses a ;TI"Ipassword, a salt, and additionally a number of iterations that will ;TI"Mslow the key derivation process down. The slower this is, the more work ;TI"=it requires being able to brute-force the resulting key.;T@%S; ;i;I"Encryption;T@%o; ;[ I"GThe strategy is to first instantiate a Cipher for encryption, and ;TI"Gthen to generate a random IV plus a key derived from the password ;TI"Jusing PBKDF2. PKCS #5 v2.0 recommends at least 8 bytes for the salt, ;TI"Ithe number of iterations largely depends on the hardware being used.;T@%o;;[I"0cipher = OpenSSL::Cipher.new 'AES-128-CBC' ;TI"cipher.encrypt ;TI"iv = cipher.random_iv ;TI" ;TI"=pwd = 'some hopefully not to easily guessable password' ;TI",salt = OpenSSL::Random.random_bytes 16 ;TI"iter = 20000 ;TI"key_len = cipher.key_len ;TI"*digest = OpenSSL::Digest::SHA256.new ;TI" ;TI"Hkey = OpenSSL::PKCS5.pbkdf2_hmac(pwd, salt, iter, key_len, digest) ;TI"cipher.key = key ;TI" ;TI"Now encrypt the data: ;TI" ;TI"(encrypted = cipher.update document ;TI"encrypted << cipher.final ;T;0S; ;i;I"Decryption;T@%o; ;[I"MUse the same steps as before to derive the symmetric AES key, this time ;TI"*setting the Cipher up for decryption.;T@%o;;[I"0cipher = OpenSSL::Cipher.new 'AES-128-CBC' ;TI"cipher.decrypt ;TI"8cipher.iv = iv # the one generated with #random_iv ;TI" ;TI"=pwd = 'some hopefully not to easily guessable password' ;TI"*salt = ... # the one generated above ;TI"iter = 20000 ;TI"key_len = cipher.key_len ;TI"*digest = OpenSSL::Digest::SHA256.new ;TI" ;TI"Hkey = OpenSSL::PKCS5.pbkdf2_hmac(pwd, salt, iter, key_len, digest) ;TI"cipher.key = key ;TI" ;TI"Now decrypt the data: ;TI" ;TI")decrypted = cipher.update encrypted ;TI"decrypted << cipher.final ;T;0S; ;i;I"&PKCS #5 Password-based Encryption;T@%o; ;[ I"CPKCS #5 is a password-based encryption standard documented at ;TI"RRFC2898[http://www.ietf.org/rfc/rfc2898.txt]. It allows a short password or ;TI"Rpassphrase to be used to create a secure encryption key. If possible, PBKDF2 ;TI"Eas described above should be used if the circumstances allow it.;T@%o; ;[I"OPKCS #5 uses a Cipher, a pass phrase and a salt to generate an encryption ;TI" key.;T@%o;;[I"5pass_phrase = 'my secure pass phrase goes here' ;TI"salt = '8 octets' ;T;0S; ;i;I"Encryption;T@%o; ;[I"+First set up the cipher for encryption;T@%o;;[I"3encryptor = OpenSSL::Cipher.new 'AES-128-CBC' ;TI"encryptor.encrypt ;TI"0encryptor.pkcs5_keyivgen pass_phrase, salt ;T;0o; ;[I"3Then pass the data you want to encrypt through;T@%o;;[I"8encrypted = encryptor.update 'top secret document' ;TI""encrypted << encryptor.final ;T;0S; ;i;I"Decryption;T@%o; ;[I"4Use a new Cipher instance set up for decryption;T@%o;;[I"3decryptor = OpenSSL::Cipher.new 'AES-128-CBC' ;TI"decryptor.decrypt ;TI"0decryptor.pkcs5_keyivgen pass_phrase, salt ;T;0o; ;[I"3Then pass the data you want to decrypt through;T@%o;;[I"(plain = decryptor.update encrypted ;TI"plain << decryptor.final ;T;0S; ;i;I"X509 Certificates;T@%S; ;i;I"Creating a Certificate;T@%o; ;[I"PThis example creates a self-signed certificate using an RSA key and a SHA1 ;TI"signature.;T@%o;;[I"'key = OpenSSL::PKey::RSA.new 2048 ;TI"=name = OpenSSL::X509::Name.parse 'CN=nobody/DC=example' ;TI" ;TI"+cert = OpenSSL::X509::Certificate.new ;TI"cert.version = 2 ;TI"cert.serial = 0 ;TI" cert.not_before = Time.now ;TI"&cert.not_after = Time.now + 3600 ;TI" ;TI"&cert.public_key = key.public_key ;TI"cert.subject = name ;T;0S; ;i;I"Certificate Extensions;T@%o; ;[I"4You can add extensions to the certificate with ;TI"OOpenSSL::SSL::ExtensionFactory to indicate the purpose of the certificate.;T@%o;;[I"Gextension_factory = OpenSSL::X509::ExtensionFactory.new nil, cert ;TI" ;TI"cert.add_extension \ ;TI"P extension_factory.create_extension('basicConstraints', 'CA:FALSE', true) ;TI" ;TI"cert.add_extension \ ;TI"+ extension_factory.create_extension( ;TI"J 'keyUsage', 'keyEncipherment,dataEncipherment,digitalSignature') ;TI" ;TI"cert.add_extension \ ;TI"J extension_factory.create_extension('subjectKeyIdentifier', 'hash') ;T;0o; ;[I"PThe list of supported extensions (and in some cases their possible values) ;TI"Ican be derived from the "objects.h" file in the OpenSSL source code.;T@%S; ;i;I"Signing a Certificate;T@%o; ;[ I"RTo sign a certificate set the issuer and use OpenSSL::X509::Certificate#sign ;TI"Swith a digest algorithm. This creates a self-signed cert because we're using ;TI"Mthe same name and key to sign the certificate as was used to create the ;TI"certificate.;T@%o;;[ I"cert.issuer = name ;TI".cert.sign key, OpenSSL::Digest::SHA1.new ;TI" ;TI"Bopen 'certificate.pem', 'w' do |io| io.write cert.to_pem end ;T;0S; ;i;I"Loading a Certificate;T@%o; ;[I"7Like a key, a cert can also be loaded from a file.;T@%o;;[I"Hcert2 = OpenSSL::X509::Certificate.new File.read 'certificate.pem' ;T;0S; ;i;I"Verifying a Certificate;T@%o; ;[I"PCertificate#verify will return true when a certificate was signed with the ;TI"given public key.;T@%o;;[I"Eraise 'certificate can not be verified' unless cert2.verify key ;T;0S; ;i;I"Certificate Authority;T@%o; ;[ I"NA certificate authority (CA) is a trusted third party that allows you to ;TI"Qverify the ownership of unknown certificates. The CA issues key signatures ;TI"Pthat indicate it trusts the user of that key. A user encountering the key ;TI";can verify the signature by using the CA's public key.;T@%S; ;i;I" CA Key;T@%o; ;[I"QCA keys are valuable, so we encrypt and save it to disk and make sure it is ;TI"!not readable by other users.;T@%o;;[ I"*ca_key = OpenSSL::PKey::RSA.new 2048 ;TI"5pass_phrase = 'my secure pass phrase goes here' ;TI" ;TI"0cipher = OpenSSL::Cipher.new 'AES-128-CBC' ;TI" ;TI"*open 'ca_key.pem', 'w', 0400 do |io| ;TI"3 io.write ca_key.export(cipher, pass_phrase) ;TI" end ;T;0S; ;i;I"CA Certificate;T@%o; ;[I"RA CA certificate is created the same way we created a certificate above, but ;TI"with different extensions.;T@%o;;[I"context.ca_file is not set ;TI"Cwhen verifying peers an OpenSSL::SSL::SSLError will be raised.;T; I"ext/openssl/ossl.c;T; 0o;;[; I"ext/openssl/ossl_asn1.c;T; 0o;;[; I"ext/openssl/ossl_bn.c;T; 0o;;[; I"ext/openssl/ossl_cipher.c;T; 0o;;[; I"ext/openssl/ossl_config.c;T; 0o;;[; I"ext/openssl/ossl_digest.c;T; 0o;;[; I"ext/openssl/ossl_engine.c;T; 0o;;[; I"ext/openssl/ossl_hmac.c;T; 0o;;[; I"ext/openssl/ossl_ns_spki.c;T; 0o;;[; I"ext/openssl/ossl_ocsp.c;T; 0o;;[; I"ext/openssl/ossl_pkcs12.c;T; 0o;;[; I"ext/openssl/ossl_pkcs5.c;T; 0o;;[; I"ext/openssl/ossl_pkcs7.c;T; 0o;;[; I"ext/openssl/ossl_pkey.c;T; 0o;;[; I"ext/openssl/ossl_rand.c;T; 0o;;[; I"ext/openssl/ossl_ssl.c;T; 0o;;[; I"#ext/openssl/ossl_ssl_session.c;T; 0o;;[; I"ext/openssl/ossl_x509.c;T; 0o;;[; I" ext/openssl/ossl_x509attr.c;T; 0o;;[; I" ext/openssl/ossl_x509cert.c;T; 0o;;[; I"ext/openssl/ossl_x509crl.c;T; 0o;;[; I"ext/openssl/ossl_x509ext.c;T; 0o;;[; I" ext/openssl/ossl_x509name.c;T; 0o;;[; I"ext/openssl/ossl_x509req.c;T; 0o;;[; I"#ext/openssl/ossl_x509revoked.c;T; 0o;;[; I"!ext/openssl/ossl_x509store.c;T; 0; 0; 0[[ U:RDoc::Constant[iI" VERSION;TI"OpenSSL::VERSION;T00o;;[o; ;[I"#OpenSSL ruby extension version;T; @_; 0@_@cRDoc::NormalModule0U;[iI"OPENSSL_VERSION;TI"OpenSSL::OPENSSL_VERSION;T00o;;[o; ;[I"AVersion of OpenSSL the ruby OpenSSL extension was built with;T; @_; 0@_@@0U;[iI"OPENSSL_LIBRARY_VERSION;TI"%OpenSSL::OPENSSL_LIBRARY_VERSION;T00o;;[o; ;[I"BVersion of OpenSSL the ruby OpenSSL extension is running with;T; @_; 0@_@@0U;[iI"OPENSSL_VERSION_NUMBER;TI"$OpenSSL::OPENSSL_VERSION_NUMBER;T00o;;[o; ;[I"IVersion number of OpenSSL the ruby OpenSSL extension was built with ;TI"(base 16);T; @_; 0@_@@0U;[iI"OPENSSL_FIPS;TI"OpenSSL::OPENSSL_FIPS;T00o;;[o; ;[I">Boolean indicating whether OpenSSL is FIPS-enabled or not;T; @_; 0@_@@0[[[I" class;T[[: public[ [I" Digest;FI"&ext/openssl/lib/openssl/digest.rb;T[I" debug;TI"ext/openssl/ossl.c;T[I" debug=;T@[I" errors;T@[I"fips_mode=;T@[I"mem_check_start;T@[I"print_mem_leaks;T@[:protected[[: private[[I" instance;T[[;[[;[[;[[@@[[U:RDoc::Context::Section[i0o;;[; 0; 0[;@ I")ext/openssl/lib/openssl/buffering.rb;T@@@@@@@_@b@e@h@k@n@q@t@w@z@}@@@@@@@@@@@@@@@I"lib/drb/ssl.rb;TI"lib/net/ftp.rb;TI"lib/net/http.rb;TI"lib/net/imap.rb;TI"lib/net/pop.rb;TI"lib/net/smtp.rb;TI"lib/open-uri.rb;TI"*lib/rubygems/commands/cert_command.rb;TI"lib/rubygems/package.rb;TI"#lib/rubygems/remote_fetcher.rb;TI"lib/rubygems/request.rb;TI"lib/rubygems/security.rb;TI"$lib/rubygems/security/policy.rb;TI"$lib/rubygems/security/signer.rb;TI"'lib/rubygems/security/trust_dir.rb;TI"lib/rubygems/test_case.rb;TI"lib/securerandom.rb;TI"lib/webrick/cgi.rb;TI"lib/webrick/server.rb;TI"lib/webrick/ssl.rb;T@cRDoc::TopLevel