spiderlabs / net-tns

Net::TNS, a Ruby library for connecting to Oracle databases.

Net::TNS for Ruby

Library for connecting to Oracle databases.

Description

Net::TNS for Ruby is a partial implementation of the TNS (Transparent Network Substrate) and TTI (Two-Task Interface, a.k.a. TTC) protocols used by Oracle Database. It allows users to connect and authenticate to databases; functionality beyond that point is limited. The library implements two protocols, and although TTI is the higher-level one, the library is named for TNS, which is more well-known.

Requirements

Net::TNS was written for and has been most tested with Ruby 2. The specs pass on 1.9.3, although their coverage is incomplete. It may be able to work with previous versions.

Installation

gem install net-tns

Use

Because TNS and TTI are highly related (and not very useful without the other), they are both implemented in this library, although in separate namespaces, Net::TNS and Net::TTI (require "net/tti" is sufficient to load both protocols, while require "net/tns" will only load the TNS implementation).

Each namespace includes a Client class, which provides access to the essential functionality for that protocol.

Examples:

Get the version of an Oracle DB server

require "net/tns" # require "net/tti" would work as well
Net::TNS::Client.get_version(:host => "10.0.0.10") # => "11.2.0.2.0"

Try authenticating to a server

require "net/tti" # requiring TTI is necessary to get the higher-level functionality
tti_client = Net::TTI::Client.new
tti_client.connect( :host => "10.0.0.10", :sid => "ORCL" )
begin
  tti_client.authenticate( "jsmith", "bananas" )
  # Authentication succeeded
rescue Net::TTI::Exceptions::InvalidCredentialsError
  # Handle invalid credentials
end
tti_client.disconnect

Contribute

Pull requests welcome! Once you've forked and cloned the project, you can bundle install to take care of the dependencies; after that, you're ready to code.

You can also create issues for any bugs or feature requests, but they may take longer to get done, of course.

Resources on TNS and TTI

• http://www.csee.umbc.edu/portal/help/oracle8/network.815/a67440/ch2.htm#1007271
• http://www.pythian.com/blog/repost-oracle-protocol/
• http://www.nyoug.org/Presentations/2008/Sep/Harris_Listening%20In.pdf
• https://community.oracle.com/thread/555302?start=0&tstart=0 (for naming of high-level components)
• http://ckng62.blogspot.com/2014/02/tns-data-packet-structure.html
• https://www.thesprawl.org/research/oracle-tns-protocol/
• The Oracle Hacker's Handbook by David Litchfield

net-tns's Issues

TNS Redirect packets are not handled

Not detecting default credentials on Oracle 11g2

When checking default credentials on Oracle 11g2, there is a NoMethod bug in the parsing of the crypto response.

require 'net/tns'
=> true
require 'net/tti'
=> true
tti_client = Net::TTI::Client.new
=> #Net::TTI::Client:0x007fadab122ab8
tti_client.connect( :host => "10.25.244.96", :sid => "orcl11g2" )
tti_client.authenticate( "test", "test" )
=> true
tti_client.authenticate( "test", "test" )
NoMethodError: undefined method chr' for true:TrueClass from /Users/jclaudius/code/net-tns/lib/net/tti/crypto.rb:141:inblock in create_combined_session_key_hash_11g'
from /Users/jclaudius/code/net-tns/lib/net/tti/crypto.rb:140:in each' from /Users/jclaudius/code/net-tns/lib/net/tti/crypto.rb:140:increate_combined_session_key_hash_11g'
from /Users/jclaudius/code/net-tns/lib/net/tti/crypto.rb:68:in get_11g_auth_values' from /Users/jclaudius/code/net-tns/lib/net/tti/client.rb:72:inget_auth_request'
from /Users/jclaudius/code/net-tns/lib/net/tti/client.rb:37:in authenticate' from (irb):5 from /Users/jclaudius/.rvm/rubies/ruby-2.1.4/bin/irb:11:in

'

TNS parsing failures under Ruby 2.1.0

This is most easily demonstrated by running rspec spec/tns/, which results in several spec failures for supposedly unregistered type IDs.

Digging into this issue further, it seems to be related to how BinData objects interact with the hash of registered packet classes.

# Ruby 2.1.0
> require "bindata"
 => true
> hash = {1 => :a}
 => {1=>:a}
> hash[BinData::Uint8.new(1)]
 => nil

# Ruby 2.1.1
> require "bindata"
 => true
> hash = {1 => :a}
 => {1=>:a}
> hash[BinData::Uint8.new(1)]
 => :a

This problem is solved easily enough where it's failing in the specs, but it deserves more investigation, as it could be causing problems in other, unspecced areas.

How to set timeout?

As title,when I use tns and tti to connect oracle instant with a ip address but not ping pong,I want to setting timeout by myself, how to deal with it, THANKS.