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/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
;T;0o;;[I"or;T@"o;;[I">key3 = OpenSSL::PKey::RSA.new File.read 'public_key.pem'
;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"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"=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"
;TI"8cipher = OpenSSL::Cipher::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"<ca_name = OpenSSL::X509::Name.parse 'CN=ca/DC=example'
;TI"
;TI".ca_cert = OpenSSL::X509::Certificate.new
;TI"ca_cert.serial = 0
;TI"ca_cert.version = 2
;TI"#ca_cert.not_before = Time.now
;TI"*ca_cert.not_after = Time.now + 86400
;TI"
;TI",ca_cert.public_key = ca_key.public_key
;TI"ca_cert.subject = ca_name
;TI"ca_cert.issuer = ca_name
;TI"
;TI"=extension_factory = OpenSSL::X509::ExtensionFactory.new
;TI"5extension_factory.subject_certificate = ca_cert
;TI"4extension_factory.issuer_certificate = ca_cert
;TI"
;TI"ca_cert.add_extension \
;TI"J  extension_factory.create_extension('subjectKeyIdentifier', 'hash')
;T;0o;;[I"?This extension indicates the CA's key may be used as a CA.;T@"o;;[I"ca_cert.add_extension \
;TI"O  extension_factory.create_extension('basicConstraints', 'CA:TRUE', true)
;T;0o;;[I"OThis extension indicates the CA's key may be used to verify signatures on ;TI"3both certificates and certificate revocations.;T@"o;;[I"ca_cert.add_extension \
;TI"+  extension_factory.create_extension(
;TI"2    'keyUsage', 'cRLSign,keyCertSign', true)
;T;0o;;[I"*Root CA certificates are self-signed.;T@"o;;[I"4ca_cert.sign ca_key, OpenSSL::Digest::SHA1.new
;T;0o;;[I"MThe CA certificate is saved to disk so it may be distributed to all the ;TI")users of the keys this CA will sign.;T@"o;;[I"%open 'ca_cert.pem', 'w' do |io|
;TI"  io.write ca_cert.to_pem
;TI"	end
;T;0S;
;i;I" Certificate Signing Request;T@"o;;[I"MThe CA signs keys through a Certificate Signing Request (CSR).  The CSR ;TI"<contains the information necessary to identify the key.;T@"o;;[
I"&csr = OpenSSL::X509::Request.new
;TI"csr.version = 0
;TI"csr.subject = name
;TI"%csr.public_key = key.public_key
;TI"-csr.sign key, OpenSSL::Digest::SHA1.new
;T;0o;;[I";A CSR is saved to disk and sent to the CA for signing.;T@"o;;[I"!open 'csr.pem', 'w' do |io|
;TI"  io.write csr.to_pem
;TI"	end
;T;0S;
;i;I"&Creating a Certificate from a CSR;T@"o;;[I"NUpon receiving a CSR the CA will verify it before signing it.  A minimal ;TI"8verification would be to check the CSR's signature.;T@"o;;[I":csr = OpenSSL::X509::Request.new File.read 'csr.pem'
;TI"
;TI"Fraise 'CSR can not be verified' unless csr.verify csr.public_key
;T;0o;;[I"MAfter verification a certificate is created, marked for various usages, ;TI":signed with the CA key and returned to the requester.;T@"o;;["I"/csr_cert = OpenSSL::X509::Certificate.new
;TI"csr_cert.serial = 0
;TI"csr_cert.version = 2
;TI"$csr_cert.not_before = Time.now
;TI")csr_cert.not_after = Time.now + 600
;TI"
;TI"$csr_cert.subject = csr.subject
;TI"*csr_cert.public_key = csr.public_key
;TI"'csr_cert.issuer = ca_cert.subject
;TI"
;TI"=extension_factory = OpenSSL::X509::ExtensionFactory.new
;TI"6extension_factory.subject_certificate = csr_cert
;TI"4extension_factory.issuer_certificate = ca_cert
;TI"
;TI"csr_cert.add_extension \
;TI"J  extension_factory.create_extension('basicConstraints', 'CA:FALSE')
;TI"
;TI"csr_cert.add_extension \
;TI"+  extension_factory.create_extension(
;TI"J    'keyUsage', 'keyEncipherment,dataEncipherment,digitalSignature')
;TI"
;TI"csr_cert.add_extension \
;TI"J  extension_factory.create_extension('subjectKeyIdentifier', 'hash')
;TI"
;TI"5csr_cert.sign ca_key, OpenSSL::Digest::SHA1.new
;TI"
;TI"&open 'csr_cert.pem', 'w' do |io|
;TI"   io.write csr_cert.to_pem
;TI"	end
;T;0S;
;i;I"SSL and TLS Connections;T@"o;;[I"SUsing our created key and certificate we can create an SSL or TLS connection. ;TI"4An SSLContext is used to set up an SSL session.;T@"o;;[I",context = OpenSSL::SSL::SSLContext.new
;T;0S;
;i;I"SSL Server;T@"o;;[I"KAn SSL server requires the certificate and private key to communicate ;TI"securely with its clients:;T@"o;;[I"context.cert = cert
;TI"context.key = key
;T;0o;;[I"QThen create an SSLServer with a TCP server socket and the context.  Use the ;TI"+SSLServer like an ordinary TCP server.;T@"o;;[I"require 'socket'
;TI"
;TI"%tcp_server = TCPServer.new 5000
;TI"Bssl_server = OpenSSL::SSL::SSLServer.new tcp_server, context
;TI"
;TI"
loop do
;TI"*  ssl_connection = ssl_server.accept
;TI"
;TI"  data = connection.gets
;TI"
;TI"'  response = "I got #{data.dump}"
;TI"  puts response
;TI"
;TI",  connection.puts "I got #{data.dump}"
;TI"  connection.close
;TI"	end
;T;0S;
;i;I"SSL client;T@"o;;[I"AAn SSL client is created with a TCP socket and the context. ;TI"NSSLSocket#connect must be called to initiate the SSL handshake and start ;TI"Oencryption.  A key and certificate are not required for the client socket.;T@"o;;[
I"require 'socket'
;TI"
;TI"2tcp_client = TCPSocket.new 'localhost', 5000
;TI"Essl_client = OpenSSL::SSL::SSLSocket.new client_socket, context
;TI"ssl_client.connect
;TI"
;TI"%ssl_client.puts "hello server!"
;TI"puts ssl_client.gets
;T;0S;
;i;I"Peer Verification;T@"o;;[I"PAn unverified SSL connection does not provide much security.  For enhanced ;TI"Jsecurity the client or server can verify the certificate of its peer.;T@"o;;[I"OThe client can be modified to verify the server's certificate against the ;TI")certificate authority's certificate:;T@"o;;[I"%context.ca_file = 'ca_cert.pem'
;TI"5context.verify_mode = OpenSSL::SSL::VERIFY_PEER
;TI"
;TI"require 'socket'
;TI"
;TI"2tcp_client = TCPSocket.new 'localhost', 5000
;TI"Essl_client = OpenSSL::SSL::SSLSocket.new client_socket, context
;TI"ssl_client.connect
;TI"
;TI"%ssl_client.puts "hello server!"
;TI"puts ssl_client.gets
;T;0o;;[I"QIf the server certificate is invalid or <tt>context.ca_file</tt> 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_digest.c;T;
0;	0;
0[[
U:RDoc::Constant[iI"VERSION;TI"OpenSSL::VERSION;F00o;;[o;;[I"#OpenSSL ruby extension version;T;	@P;
0@P@cRDoc::NormalModule0U;[iI"OPENSSL_VERSION;TI"OpenSSL::OPENSSL_VERSION;F00o;;[o;;[I"AVersion of OpenSSL the ruby OpenSSL extension was built with;T;	@P;
0@P@@h0U;[iI"OPENSSL_LIBRARY_VERSION;TI"%OpenSSL::OPENSSL_LIBRARY_VERSION;F00o;;[o;;[I"BVersion of OpenSSL the ruby OpenSSL extension is running with;T;	@P;
0@P@@h0U;[iI"OPENSSL_VERSION_NUMBER;TI"$OpenSSL::OPENSSL_VERSION_NUMBER;F00o;;[o;;[I"IVersion number of OpenSSL the ruby OpenSSL extension was built with ;TI"(base 16);T;	@P;
0@P@@h0U;[iI"OPENSSL_FIPS;TI"OpenSSL::OPENSSL_FIPS;F00o;;[;	@P;
0@P@@h0[[[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@—[:protected[[:private[[I"
instance;T[[;[[;[[;[[@“@”[[U:RDoc::Context::Section[i0o;;[;	0;
0[0@I")ext/openssl/lib/openssl/buffering.rb;T@@@@@@P@S@V@Y@\I"ext/openssl/ossl_hmac.c;TI"ext/openssl/ossl_ns_spki.c;TI"ext/openssl/ossl_pkcs5.c;TI"ext/openssl/ossl_pkey.c;TI"ext/openssl/ossl_pkey_dh.c;TI" ext/openssl/ossl_pkey_dsa.c;TI"ext/openssl/ossl_pkey_ec.c;TI" ext/openssl/ossl_pkey_rsa.c;TI"ext/openssl/ossl_rand.c;TI"ext/openssl/ossl_ssl.c;TI"#ext/openssl/ossl_ssl_session.c;TI" ext/openssl/ossl_x509cert.c;TI"!ext/openssl/ossl_x509store.c;TI"lib/drb/ssl.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/ssl.rb;T@ÀcRDoc::TopLevel