Class: Net::LDAP::DN

Inherits:
Object
  • Object
show all
Defined in:
lib/net/ldap/dn.rb

Overview

Objects of this class represent an LDAP DN (“Distinguished Name”). A DN (“Distinguished Name”) is a unique identifier for an entry within an LDAP directory. It is made up of a number of other attributes strung together, to identify the entry in the tree.

Each attribute that makes up a DN needs to have its value escaped so that the DN is valid. This class helps take care of that.

A fully escaped DN needs to be unescaped when analysing its contents. This class also helps take care of that.

Constant Summary collapse

ESCAPES =

tools.ietf.org/html/rfc2253 section 2.4 lists these exceptions for dn values. All of the following must be escaped in any normal string using a single backslash (‘') as escape.

%w[, + " \\ < > ;]
ESCAPE_RE =

Compiled character class regexp using the values from the above list, and checking for a space or # at the start, or space at the end, of the string.

Regexp.new("(^ |^#| $|[" +
ESCAPES.map { |e| Regexp.escape(e) }.join +
"])")

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ DN

Initialize a DN, escaping as required. Pass in attributes in name/value pairs. If there is a left over argument, it will be appended to the dn without escaping (useful for a base string).

Most uses of this class will be to escape a DN, rather than to parse it, so storing the dn as an escaped String and parsing parts as required with a state machine seems sensible.



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/net/ldap/dn.rb', line 23

def initialize(*args)
  buffer = StringIO.new

  args.each_index do |index|
    buffer << "=" if index % 2 == 1
    buffer << "," if index % 2 == 0 && index != 0

    if index < args.length - 1 || index % 2 == 1
      buffer << Net::LDAP::DN.escape(args[index])
    else
      buffer << args[index]
    end
  end

  @dn = buffer.string
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *args, &block) ⇒ Object

Proxy all other requests to the string object, because a DN is mainly used within the library as a string



213
214
215
 
# File 'lib/net/ldap/dn.rb', line 213

def method_missing(method, *args, &block)
  @dn.send(method, *args, &block)
end

Class Method Details

.escape(string) ⇒ Object

Escape a string for use in a DN value



206
207
208
 
# File 'lib/net/ldap/dn.rb', line 206

def self.escape(string)
  string.gsub(ESCAPE_RE) { |char| "\\" + char }
end

Instance Method Details

#each_pair {|key.string.strip, value.string| ... } ⇒ Object

Parse a DN into key value pairs using ASN from tools.ietf.org/html/rfc2253 section 3.

Yields:

  • (key.string.strip, value.string)

Raises:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/net/ldap/dn.rb', line 43

def each_pair
  state = :key
  key = StringIO.new
  value = StringIO.new
  hex_buffer = ""

  @dn.each_char do |char|
    case state
    when :key then
      case char
      when 'a'..'z', 'A'..'Z' then
        state = :key_normal
        key << char
      when '0'..'9' then
        state = :key_oid
        key << char
      when ' ' then state = :key
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :key_normal then
      case char
      when '=' then state = :value
      when 'a'..'z', 'A'..'Z', '0'..'9', '-', ' ' then key << char
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :key_oid then
      case char
      when '=' then state = :value
      when '0'..'9', '.', ' ' then key << char
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :value then
      case char
      when '\\' then state = :value_normal_escape
      when '"' then state = :value_quoted
      when ' ' then state = :value
      when '#' then
        state = :value_hexstring
        value << char
      when ',' then
        state = :key
        yield key.string.strip, value.string
        key = StringIO.new
        value = StringIO.new;
      else
        state = :value_normal
        value << char
      end
    when :value_normal then
      case char
      when '\\' then state = :value_normal_escape
      when ',' then
        state = :key
        yield key.string.strip, value.string
        key = StringIO.new
        value = StringIO.new;
      else value << char
      end
    when :value_normal_escape then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_normal_escape_hex
        hex_buffer = char
      else state = :value_normal; value << char
      end
    when :value_normal_escape_hex then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_normal
        value << "#{hex_buffer}#{char}".to_i(16).chr
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :value_quoted then
      case char
      when '\\' then state = :value_quoted_escape
      when '"' then state = :value_end
      else value << char
      end
    when :value_quoted_escape then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_quoted_escape_hex
        hex_buffer = char
      else
        state = :value_quoted;
        value << char
      end
    when :value_quoted_escape_hex then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_quoted
        value << "#{hex_buffer}#{char}".to_i(16).chr
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :value_hexstring then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_hexstring_hex
        value << char
      when ' ' then state = :value_end
      when ',' then
        state = :key
        yield key.string.strip, value.string
        key = StringIO.new
        value = StringIO.new;
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :value_hexstring_hex then
      case char
      when '0'..'9', 'a'..'f', 'A'..'F' then
        state = :value_hexstring
        value << char
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    when :value_end then
      case char
      when ' ' then state = :value_end
      when ',' then
        state = :key
        yield key.string.strip, value.string
        key = StringIO.new
        value = StringIO.new;
      else raise Net::LDAP::InvalidDNError, "DN badly formed"
      end
    else raise Net::LDAP::InvalidDNError, "Fell out of state machine"
    end
  end

  # Last pair
  raise Net::LDAP::InvalidDNError, "DN badly formed" unless
    [:value, :value_normal, :value_hexstring, :value_end].include? state

  yield key.string.strip, value.string
end

#to_a ⇒ Object

Returns the DN as an array in the form expected by the constructor.



180
181
182
183
184
 
# File 'lib/net/ldap/dn.rb', line 180

def to_a
  a = []
  self.each_pair { |key, value| a << key << value }
  a
end

#to_s ⇒ Object

Return the DN as an escaped string.



188
189
190
 
# File 'lib/net/ldap/dn.rb', line 188

def to_s
  @dn
end