Class: Gsasl::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/gsasl/context.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Context

Create a new gsasl authentication context.



9
10
11
12
13
14
15
16
17
 
# File 'lib/gsasl/context.rb', line 9

def initialize
  ctx = FFI::MemoryPointer.new :pointer
  result = Gsasl.gsasl_init(ctx)
  @context = ctx.get_pointer(0)
  Gsasl.raise_error!(result)
  @peers = {}
  Gsasl.new_context @context.address, self
  Gsasl.gsasl_callback_set(@context, CALLBACK)
end

Instance Attribute Details

#peers ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Access the peers of a given session. This is used to find peers for the global ‘Gsasl::CALLBACK`.



6
7
8
 
# File 'lib/gsasl/context.rb', line 6

def peers
  @peers
end

Instance Method Details

#authenticate_with(mechanism, authid, password) {|remote| ... } ⇒ Boolean

Authenticate against a remote peer using a socket like authenication scheme.

Examples:

Authenticate against an imap server with PLAIN authentication

# connect to an imap server
require 'socket'
socket = TCPSocket.new('imap.example.com', 143)
puts socket.gets

# issue an authenticate command
socket.print "a1 AUTHENTICATE PLAIN\r\n"

# authenticate using the imap4 protocol specifics
context = Gsasl::Context.new
context.authenticate_with("PLAIN", "[email protected]", "pass") do |remote|
  remote.receive { socket.gets.gsub!("\r\n|+\s", "") }
  remote.send    { |data| socket.print "#{data}\r\n" }
end
puts socket.gets # => capabilities after authentication

# logout
socket.print "a2 LOGOUT\r\n"
puts socket.gets

# close connection
socket.close
context.close

Parameters:

  • mechanism (String) —

    the SASL mechanism to use

  • authid (String) —

    the username auth id of the user to use for auth.

  • password (String) —

    the password of the specified user

Yields:

  • (remote) —

    the block that defines how to interact with the remote site

Yield Parameters:

  • remote (Gsasl::RemoteAuthenticator) —

    the remote authenticator that needs to be defined in order for gsasl to receive and set data.

Returns:

  • (Boolean) —

    true if the authentication was successful, false otherwise



121
122
123
124
125
126
 
# File 'lib/gsasl/context.rb', line 121

def authenticate_with(mechanism, authid, password, &block)
  client = create_client(mechanism)
  client.credentials!(authid, password)
  client.authenticate_with(&block)
  client.close
end

#client_mechanisms ⇒ Array<String>

Returns a list of mechanisms for the client peer

Returns:

  • (Array<String>) —

    the list of possible mechanisms



54
55
56
 
# File 'lib/gsasl/context.rb', line 54

def client_mechanisms
  mechanisms :client
end

#client_support_for?(mechanism_name) ⇒ Boolean

Checks if the client peer supports the passed mechanism

Parameters:

  • mechanism_name (String) —

    the mechnism to check for

Returns:

  • (Boolean) —

    true if it is supported false otherwise



30
31
32
 
# File 'lib/gsasl/context.rb', line 30

def client_support_for?(mechanism_name)
  Gsasl.gsasl_client_support_p(@context, mechanism_name) == 1
end

#close ⇒ Object

Closes the sasl peer for the context. Should be called after authenication.



42
43
44
 
# File 'lib/gsasl/context.rb', line 42

def close
  Gsasl.gsasl_done(@context)
end

#create_client(mechanism_name) ⇒ Gsasl::Peer

Creates the client peer based on the passed mechanism

Examples:

peer = @session.create_client("CRAM-MD5")

Parameters:

  • mechanism_name (String) —

    the name of the mechanism

Returns:



80
81
82
83
84
 
# File 'lib/gsasl/context.rb', line 80

def create_client(mechanism_name)
  peer = Peer.new(@context, mechanism_name, :client)
  @peers[peer.session.address] = peer
  peer
end

#create_server(mechanism_name, realm = "gsasl", &block) ⇒ Gsasl::Peer

Creates the server peer based on the passed mechanism

Examples:

peer = @session.create_server("CRAM-MD5")

Server with password database attached directly

peer = @session.create_server("CRAM-MD5") do |type, authid|
  DB.find_password_for_user(auth_id) if type == :password
end

Parameters:

  • mechanism_name (String) —

    the name of the mechanism

Returns:



67
68
69
70
71
72
73
 
# File 'lib/gsasl/context.rb', line 67

def create_server(mechanism_name, realm = "gsasl", &block)
  peer = Peer.new(@context, mechanism_name, :server)
  @peers[peer.session.address] = peer
  peer.realm = realm
  peer.authentication_callback = block if block_given?
  peer
end

#server_mechanisms ⇒ Array<String>

Returns a list of mechanisms for the server peer

Returns:

  • (Array<String>) —

    the list of possible mechanisms



48
49
50
 
# File 'lib/gsasl/context.rb', line 48

def server_mechanisms
  mechanisms :server
end

#server_support_for?(mechanism_name) ⇒ Boolean

Checks if the server peer supports the passed mechanism

Parameters:

  • mechanism_name (String) —

    the mechnism to check for

Returns:

  • (Boolean) —

    true if it is supported false otherwise



37
38
39
 
# File 'lib/gsasl/context.rb', line 37

def server_support_for?(mechanism_name)
  Gsasl.gsasl_server_support_p(@context, mechanism_name) == 1
end

#version(check = nil) ⇒ String?

Returns or checks agains the passed version of GNU SASL.

Parameters:

  • check (String) (defaults to: nil) —

    the version string to check against.

Returns:

  • (String, nil) —

    the version string if the check was successful, nil otherwise



23
24
25
 
# File 'lib/gsasl/context.rb', line 23

def version(check = nil)
  Gsasl.gsasl_check_version check
end