source3/nameservreply.doc

   1 /*
   2    Unix SMB/Netbios documentation.
   3    Version 0.0
   4    Copyright (C) Luke Leighton  Andrew Tridgell  1996
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19
  20    Document name: nameservreply.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26 */
  27
  28 /*************************************************************************
  29   reply_name_query()
  30   *************************************************************************/
  31
  32 this function is responsible for replying to a NetBIOS name query.
  33
  34 there are two kinds of name queries: directed, and broadcast. directed
  35 queries are usually sent to samba in its WINS capacity. such hosts are
  36 termed 'point-to-point' hosts. broadcast queries are usually sent from
  37 'broadcast' or 'mixed' hosts.
  38
  39 broadcasting is used by either older NetBIOS hosts, new NetBIOS hosts that
  40 have not had WINS capabilities added and new NetBIOS hosts that think the
  41 WINS server has died.
  42
  43 the samba NetBIOS name database is divided into sections, on a
  44 per-subnet basis. there is also a WINS NetBIOS name database, and for
  45 convenience this is added as a pseudo-subnet with the ip address of
  46 255.255.255.255.
  47
  48 the local subnet NetBIOS name databases only contain samba's names.
  49 the reason for this is that if a broadcast query is received, a NetBIOS
  50 hosts is only expected to respond if that query is for one of its own
  51 names (the exception to this is if a host is configured as a 'proxy'
  52 server, in which case, samba should redirect the query to another WINS
  53 server).
  54
  55 the WINS pseudo-subnet NetBIOS database contains all NetBIOS names
  56 that are not 'special browser' type names (regarding this i am a
  57 _bit_ confused :-). names of type 0x01, 0x1d and 0x1e i consider to
  58 be 'special browser' names. at the moment. maybe.
  59
  60 the type of search to be initiated is determined. if the NetBIOS name
  61 type is a non-special-browser name, then the WINS database is included
  62 in the search.
  63
  64 if the name is not a special browser name, then we need to find the
  65 right subnet that the query came from. this is done using
  66 find_req_subnet(). this also has the benefit of stopping any queries
  67 from subnets that samba does not know about.
  68
  69 if the query is a broadcast query, then the database of the local subnet
  70 is included in the search.
  71
  72 the name is then searched for in the appropriate NetBIOS data structures.
  73 if it is found, then we need to check whether it is appropriate for us
  74 to reply to such a query.
  75
  76 we will only reply if the query is a directed query, the name belongs to
  77 samba on that subnet, or the name is a domain master browser type,
  78 or we're doing replies on behalf of hosts on subnets not known to the
  79 host issuing the query. in the latter instance, it would be appropriate
  80 if samba is using a WINS server for it to forward the name query on to
  81 this WINS server.
  82
  83 reply_name_query() then takes note of all the information that is
  84 needed to construct a reply to the caller. a negative reply (if the
  85 name is unknown to samba) or a positive reply (the name is known to
  86 samba) is then issued.
  87
  88
  89 /*************************************************************************
  90   reply_name_status()
  91   *************************************************************************/
  92
  93 this function is responsible for constructing a reply to a NetBIOS
  94 name status query. this response contains all samba's NetBIOS names
  95 on the subnet that the query came in from.
  96
  97 a reply will only be made if the NetBIOS name being queried exists.
  98
  99 see rfc1001.txt and rfc1002.txt for details of the name status reply.
 100
 101
 102 /*************************************************************************
 103   reply_name_reg()
 104   *************************************************************************/
 105
 106 this function is responsible for updating the NetBIOS name database
 107 from registration packets sent out by hosts wishing to register a
 108 name, and for informing them, if necessary, if this is acceptable
 109 or not.
 110
 111 name registration can be done by broadcast or by point-to-point,
 112 i.e the registration is sent directly to samba in its capacity as
 113 a WINS server.
 114
 115 if the name registration is done by broadcast (see rfc1001.txt 15.2.1),
 116 then samba's involvement in replying is limited to whether that name
 117 is owned by samba or not, on the relevant subnet.
 118
 119 if the name registration is done point-to-point (see rfc1001.txt 15.2.2)
 120 then samba will first need to check its WINS name database records and
 121 proceed accordingly.
 122
 123 samba looks for the appropriate subnet record that the registration
 124 should be added to / checked against, using find_req_subnet().
 125
 126 next, the name is searched for in the local database or the WINS
 127 database as appropriate.
 128
 129 if the name is not found, then it is added to the NetBIOS name database,
 130 using add_netbios_entry(), which may choose not to add the name (not
 131 that this affects the registration of the name on the network in any way).
 132 it will only add names to the WINS database, and even then it will only
 133 add non-special-browser type names.
 134
 135 if the name is found, then samba must decide whether to accept the name
 136 or not. a group name is always added. for unique names, further checks
 137 need to be carried out.
 138
 139 firstly, if the name in the database is one of samba's names, or if the
 140 name in the database is a group name, then it cannot be added as a unique
 141 name belonging to someone else. it is therefore rejected.
 142
 143 secondly, if the ip address of the name being registered does not match
 144 against the ip in the database, then the unique name may belong to
 145 someone else. a check needs to be carried out with the owner in case
 146 they still wish to keep this name. a detailed discussion of what action
 147 to take is in rfc1001.txt 15.2.2.2 and 15.2.2.3.
 148
 149 samba currently implements non-secured WINS, whereupon the responsibility
 150 for checking the name is passed on to the host doing the registration.
 151 rfc1001.txt refers to this as an END-NODE CHALLENGE REGISTRATION RESPONSE.
 152 (samba itself cannot yet cope with receiving such responses if it
 153 registers its names with another WINS server).
 154
 155 having decided what kind of response to send (if any - acceptance of
 156 name registrations by broadcast is implicit), samba will send either a
 157 positive or negative NAME REGISTRATION RESPONSE, or an END-NODE CHALLENGE
 158 REGISTRATION RESPONSE to the host that initially sent the registration.
 159
 160 whew.
 161
 162
 163 /*************************************************************************
 164   reply_name_release()
 165   *************************************************************************/
 166
 167 this function is responsible for removing a NetBIOS name from the
 168 database when a server sends a release packet.
 169
 170 samba looks for the appropriate subnet record that the release should
 171 be removed from, using find_req_subnet(). next, the name is searched
 172 for in the local database or the WINS database as appropriate.
 173
 174 if the name is found, it is removed from the database and a
 175 positive reply is sent confirming this. if the name is not
 176 found, a negative reply is sent.
 177
 178 a reply is _not_ sent if the release was done by broadcast: the
 179 release is implicit, and we should be grateful that they bothered
 180 to tell us. if the release was done by directed packet, then
 181 we deal with it as a WINS server and must reply (pos / neg).
 182
 183 at present, the criteria for removing a name have yet to be
 184 developed / experimented with. at present, the only flags that
 185 are checked are the NetBIOS flags.
 186
 187
 188 /*************************************************************************
 189   send_name_response()
 190   *************************************************************************/
 191
 192 this function is a wrap around reply_netbios_packet(). it sends
 193 a response to a name registration or release packet, minimising
 194 the function parameters needed to do this.
 195
 196 if the function is called with the parameter 'success' set to
 197 True, then a positive response (to the registration or release)
 198 is made (see rfc1002.txt 4.2.5 and 4.2.10). if this parameter
 199 is False, then a negative response is issued (see rfc1002.txt
 200 4.2.6 and 4.2.11)
 201
 202 if the function is called with a registration code, and the
 203 parameter 'recurse' is False, then an End-Node Challenge
 204 Registration response is issued (see rfc1002.txt 4.2.7)
 205
 206 note: this function could also easily be used for name conflict
 207 demand (see rfc1002.txt 4.2.8).
 208
 209 note: End-Node Challenge Registration response is only sent in
 210 non-secured NetBIOS Name Server implementations. samba now
 211 implements secured NetBIOS Name Server functionality (see
 212 rfc1001.txt 15.1.6).
 213