Parent

Net::LdapPdu

Constants

BindRequest
BindResult
UnbindRequest
SearchRequest
SearchReturnedData
SearchResult
ModifyResponse
AddResponse
DeleteResponse
ModifyRDNResponse
SearchResultReferral
ExtendedRequest
ExtendedResponse

Attributes

msg_id[R]
app_tag[R]
search_dn[R]
search_attributes[R]
search_entry[R]
search_referrals[R]
search_parameters[R]
bind_parameters[R]

Public Class Methods

new(ber_object) click to toggle source

An LDAP PDU always looks like a BerSequence with at least two elements: an integer (message-id number), and an application-specific sequence. Some LDAPv3 packets also include an optional third element, which is a sequence of “controls” (See RFC 2251, section 4.1.12). The application-specific tag in the sequence tells us what kind of packet it is, and each kind has its own format, defined in RFC-1777. Observe that many clients (such as ldapsearch) do not necessarily enforce the expected application tags on received protocol packets. This implementation does interpret the RFC strictly in this regard, and it remains to be seen whether there are servers out there that will not work well with our approach.

Added a controls-processor to SearchResult. Didn’t add it everywhere because it just feels like it will need to be refactored.

     # File lib/net/ldap/pdu.rb, line 71
 71:                 def initialize ber_object
 72:                         begin
 73:                                 @msg_id = ber_object[0].to_i
 74:                                 # Modified 25Nov06. We want to "un-decorate" the ber-identifier
 75:                                 # of the incoming packet. Originally we did this by subtracting 0x60,
 76:                                 # which ASSUMES the identifier is a constructed app-specific value.
 77:                                 # But at least one value (UnbindRequest) is app-specific primitive.
 78:                                 # So it makes more sense just to grab the bottom five bits.
 79:                                 #@app_tag = ber_object[1].ber_identifier - 0x60
 80:                                 @app_tag = ber_object[1].ber_identifier & 31
 81:                                 @ldap_controls = []
 82:                         rescue
 83:                                 # any error becomes a data-format error
 84:                                 raise LdapPduError.new( "ldap-pdu format error" )
 85:                         end
 86: 
 87:                         case @app_tag
 88:                         when BindResult
 89:                                 parse_bind_response ber_object[1]
 90:                         when SearchReturnedData
 91:                                 parse_search_return ber_object[1]
 92:                         when SearchResultReferral
 93:                                 parse_search_referral ber_object[1]
 94:                         when SearchResult
 95:                                 parse_ldap_result ber_object[1]
 96:                                 parse_controls(ber_object[2]) if ber_object[2]
 97:                         when ModifyResponse
 98:                                 parse_ldap_result ber_object[1]
 99:                         when AddResponse
100:                                 parse_ldap_result ber_object[1]
101:                         when DeleteResponse
102:                                 parse_ldap_result ber_object[1]
103:                         when ModifyRDNResponse
104:                                 parse_ldap_result ber_object[1]
105:                         when SearchRequest
106:                                 parse_ldap_search_request ber_object[1]
107:                         when BindRequest
108:                                 parse_bind_request ber_object[1]
109:                         when UnbindRequest
110:                                 parse_unbind_request ber_object[1]
111:                         when ExtendedResponse
112:                                 parse_ldap_result ber_object[1]
113:                         else
114:                                 raise LdapPduError.new( "unknown pdu-type: #{@app_tag}" )
115:                         end
116:                 end

Public Instance Methods

parse_bind_request(sequence) click to toggle source

(provisional, must document)

     # File lib/net/ldap/pdu.rb, line 244
244:                 def parse_bind_request sequence
245:                         s = OpenStruct.new
246:                         s.version,
247:                                 s.name,
248:                                 s.authentication = sequence
249:                         @bind_parameters = s
250:                 end
parse_ldap_search_request(sequence) click to toggle source

(provisional, must document)

     # File lib/net/ldap/pdu.rb, line 230
230:                 def parse_ldap_search_request sequence
231:                         s = OpenStruct.new
232:                         s.base_object,
233:                                 s.scope,
234:                                 s.deref_aliases,
235:                                 s.size_limit,
236:                                 s.time_limit,
237:                                 s.types_only,
238:                                 s.filter,
239:                                 s.attributes = sequence
240:                         @search_parameters = s
241:                 end
parse_search_referral(uris) click to toggle source

A search referral is a sequence of one or more LDAP URIs. Any number of search-referral replies can be returned by the server, interspersed with normal replies in any order. Until I can think of a better way to do this, we’ll return the referrals as an array. It’ll be up to higher-level handlers to expose something reasonable to the client.

     # File lib/net/ldap/pdu.rb, line 204
204:                 def parse_search_referral uris
205:                         @search_referrals = uris
206:                 end
parse_search_return(sequence) click to toggle source

Definition from RFC 1777 (we’re handling application-4 here)

Search Response ::=

   CHOICE {
        entry          [APPLICATION 4] SEQUENCE {
                            objectName     LDAPDN,
                            attributes     SEQUENCE OF SEQUENCE {
                                                AttributeType,
                                                SET OF AttributeValue
                                           }
                       },
        resultCode     [APPLICATION 5] LDAPResult
    }

We concoct a search response that is a hash of the returned attribute values. NOW OBSERVE CAREFULLY: WE ARE DOWNCASING THE RETURNED ATTRIBUTE NAMES. This is to make them more predictable for user programs, but it may not be a good idea. Maybe this should be configurable. ALTERNATE IMPLEMENTATION: In addition to @search_dn and @search_attributes, we also return @search_entry, which is an LDAP::Entry object. If that works out well, then we’ll remove the first two.

Provisionally removed obsolete search_attributes and search_dn, 04May06.

     # File lib/net/ldap/pdu.rb, line 191
191:                 def parse_search_return sequence
192:                         sequence.length >= 2 or raise LdapPduError
193:                         @search_entry = LDAP::Entry.new( sequence[0] )
194:                         sequence[1].each {|seq|
195:                                 @search_entry[seq[0]] = seq[1]
196:                         }
197:                 end
parse_unbind_request(sequence) click to toggle source

(provisional, must document) UnbindRequest has no content so this is a no-op.

     # File lib/net/ldap/pdu.rb, line 254
254:                 def parse_unbind_request sequence
255:                 end
result() click to toggle source

Returns a hash which (usually) defines the members :resultCode, :errorMessage, and :matchedDN. These values come directly from an LDAP response packet returned by the remote peer. See # for a sugaring.

     # File lib/net/ldap/pdu.rb, line 122
122:                 def result
123:                         @ldap_result || {}
124:                 end
result_code(code = :resultCode) click to toggle source

This returns an LDAP result code taken from the PDU, but it will be nil if there wasn’t a result code. That can easily happen depending on the type of packet.

     # File lib/net/ldap/pdu.rb, line 130
130:                 def result_code code = :resultCode
131:                         @ldap_result and @ldap_result[code]
132:                 end
result_controls() click to toggle source

Return RFC-2251 Controls if any. Messy. Does this functionality belong somewhere else?

     # File lib/net/ldap/pdu.rb, line 136
136:                 def result_controls
137:                         @ldap_controls
138:                 end
result_server_sasl_creds() click to toggle source

Return serverSaslCreds, which are only present in BindResponse packets. Messy. Does this functionality belong somewhere else? We ought to refactor the accessors of this class before they get any kludgier.

     # File lib/net/ldap/pdu.rb, line 143
143:                 def result_server_sasl_creds
144:                         @ldap_result && @ldap_result[:serverSaslCreds]
145:                 end

Private Instance Methods

parse_bind_response(sequence) click to toggle source

A Bind Response may have an additional field, ID [7], serverSaslCreds, per RFC 2251 pgh 4.2.3.

     # File lib/net/ldap/pdu.rb, line 158
158:                 def parse_bind_response sequence
159:                         sequence.length >= 3 or raise LdapPduError
160:                         @ldap_result = {:resultCode => sequence[0], :matchedDN => sequence[1], :errorMessage => sequence[2]}
161:                         @ldap_result[:serverSaslCreds] = sequence[3] if sequence.length >= 4
162:                         @ldap_result
163:                 end
parse_controls(sequence) click to toggle source

Per RFC 2251, an LDAP “control” is a sequence of tuples, each consisting of an OID, a boolean criticality flag defaulting FALSE, and an OPTIONAL Octet String. If only two fields are given, the second one may be either criticality or data, since criticality has a default value. Someday we may want to come back here and add support for some of more-widely used controls. RFC-2696 is a good example.

     # File lib/net/ldap/pdu.rb, line 215
215:                 def parse_controls sequence
216:                         @ldap_controls = sequence.map do |control|
217:                                 o = OpenStruct.new
218:                                 o.oid,o.criticality,o.value = control[0],control[1],control[2]
219:                                 if o.criticality and o.criticality.is_a?(String)
220:                                         o.value = o.criticality
221:                                         o.criticality = false
222:                                 end
223:                                 o
224:                         end
225:                 end
parse_ldap_result(sequence) click to toggle source

parse_ldap_result

     # File lib/net/ldap/pdu.rb, line 149
149:                 def parse_ldap_result sequence
150:                         sequence.length >= 3 or raise LdapPduError
151:                         @ldap_result = {:resultCode => sequence[0], :matchedDN => sequence[1], :errorMessage => sequence[2]}
152:                 end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.