LanMan98 3.00 Beta 3 with SMB2
==============================
An updated !LanMan98 client, and a suite for testing it on a real machine.

  !LanMan98    the client, ready to run.  Drop it in place of your existing
               copy, or run it from here.
  TestSuite    tests you can run against your own server.  See its !ReadMe.
  Changes      what changed, in detail.
  LanMan98-PRM the programmer's reference manual, as a PDF: the commands,
               the SWIs, the system variables and how the protocol side
               of it behaves.
               
AI Disclosure
-------------

AI has been used in some portions of LanMan98 v3 to speed up development.
The work has been extensively human-driven and human-tested.  However,
as with any AI-assisted project, it is possible that humans have missed
something, and we apologise in advance if this is the case.  That is why
the software is going through extensive beta test.

The AI has only been provided with LM98 source code and the SMB 2/3
specification documents to minimise the risk of cross-pollination.  It
has also been instructed on the CDDL licence.  However, it is still
possible that mistakes are made - we will endeavour to rectify any
issues raised as quickly as possible, provided they are first identified
to us directly at info@riscosdev.com

If you are unwilling to accept the above, we completely understand, but
ask that you please refrain from using v3 the software.  The older
LanMan98 version 2 software (up to 2.08) remains untouched by AI.


New in Beta 3
-------------
It speaks SMB 3.1.1, which is what an unrestricted server will now settle
on.  3.1.1 negotiates by listing what the client can do rather than
declaring it in a capabilities word, and it protects the negotiation with a
running SHA-512 whose value goes into the keys - so a listener that alters
what was agreed makes the two ends derive different keys and the session
fails, instead of the negotiation quietly settling on whatever suited the
listener.  A 3.1.1 connection is always signed, for the same reason.

    Set LanMan98$SMB3 ""

still means 3.0 and 3.0.2 only, which is also how to ask for a connection
without 3.1.1.


New in Beta 2
-------------
Traffic can now be encrypted.  An SMB 3 connection negotiates AES-128-CCM,
so file names and file contents no longer cross the network in clear.
Signing, which this client has done for a while, proves a message was not
altered on the way; it hides nothing.  Encryption comes on by itself when
the server asks for it - which is what makes shares configured to demand
it reachable at all, where before the connection was simply refused - and

    Set LanMan98$Encrypt ""

in !Run insists on it everywhere.

Reaching a server across something slower than a local network is better
served in two other ways.  LanMan98$KeepAlive, LanMan98$Timeout and
LanMan98$ConnectTimeout raise the waits and shorten the interval an idle
connection is held up by, which matters where a NAT on the path forgets a
mapping sooner than the client prods it.  And the last read of a file no
longer costs a wasted round trip: a short read is now taken as the end
rather than asking again to be told so.

Two things the client never noticed before, it now notices by itself.

  * A directory changed by somebody else refreshes.  A file another
    machine adds to, changes or removes from a share appears in, or
    disappears from, an open Filer window without the window being
    touched.  A change made on this machine always showed up, because
    FileSwitch announces it; nothing announced a change made elsewhere,
    and there is nothing on the wire to listen for either, so the
    directory a viewer is showing is re-read on a timer and compared.

        Set LanMan98$WatchPeriod 500

    is the interval in centiseconds, and 0 turns it off.

  * A server appearing on the network is noticed.  A machine switched on
    after the desktop started, or one that joins later, is found without
    anybody thinking to look for it, and its name is put in LanMan98$New.
    *Discover98 has asked the network what is on it since 2.60, but only
    when somebody thinks to ask; the same question on a timer notices by
    itself, and costs one packet.

        Set LanMan98$SweepPeriod 30000

    in !Run changes the interval, in centiseconds; 0 turns it off.
    It runs every five minutes without being asked.

    The Filer says so in a small window in the top right
    corner, which takes itself away after fifteen seconds or when you
    click it.  It is deliberately not an error box: those are modal, and
    hold the whole desktop until dismissed.  The servers already announced are remembered in
    LanMan98$SeenFile, by default <Choices$Write>.LanMan98Seen, so a
    reboot does not announce the whole network over again.

    What each server *shares* is still only asked for when you ask, on
    *Discover98.  Finding that out needs a connection and a logon to
    every machine on the network, which is not a thing to do on a timer.


If you are updating, do so
--------------------------
2.76 fixes the "Bad buffer size" that stopped a file being opened at all on
a 26 bit RISC OS - VirtualRPC and RISC OS Adjust.  Nothing before it works
there.


2.73 fixed a bug that destroyed files, and 2.75 corrects that fix.  Over SMB2, opening a file for
writing truncated it to nothing before handing it back - opening was enough,
nothing had to be written.  Archives were the common casualty, because
opening a Zip to look inside it opens it for update; such a file came out
its original size and full of zeros, and was then shown as an empty archive
and retyped Tar.  Files already emptied are zeros on the server and cannot
be recovered by this end; restore them from a backup.


What is different
-----------------
The old client could only speak to a server willing to use the original SMB
protocol, over NetBIOS, with the original password scheme.  Every current
system has turned all three of those off.  This one:

  * connects on port 445 as well as 139, trying 445 first
  * authenticates through NTLMSSP, which is what a current server will
    accept.  Putting an NTLMv2 response straight into the request - the way
    this used to work, and the way the released client still does - has been
    refused by Samba since version 4.5, so every recent Linux NAS, Synology
    and QNAP included, answered "Invalid parameter" and would not mount.
    Servers too old to offer it still get NTLMv2, then NTLMv1, then LM
  * reports what actually went wrong, by name, instead of "Access denied"
    for everything
  * looks names up through the naming service before asking NetBIOS
  * keeps file dates as the server holds them, rather than rounding them to
    the nearest two seconds
  * moves files in sixty kilobyte pieces rather than half a kilobyte
  * can speak SMB2, which is what Windows and macOS offer now, and falls
    back to it on its own for a server that has SMB1 switched off
  * signs its messages, in every protocol it speaks, so a server that
    insists on signing will talk to it
  * speaks SMB 3.0 and 3.0.2 as well as 2.0.2 and 2.1
  * converts names through the RISC OS alphabet, so the characters at
    &80-&9F - the Euro sign, the curly quotes, the dashes, the ligatures -
    survive a round trip instead of arriving as control codes one way and
    full stops the other

Everything except SMB2 is on by default and needs nothing set up.


Which protocol is used
----------------------
SMB2 is tried first and the older protocol only if a server will not answer
it.  The highest both ends know is used, which today usually means SMB 3.0.2.
Nothing needs setting.

    Set LanMan98$NoSMB2 ""

goes back to trying the old protocol first, for a server that answers SMB2
and then handles it badly.

    Set LanMan98$SMB2Only ""

refuses to fall back at all: a connection either uses SMB2 or says why it
could not.  That is for finding out what a machine is really doing rather
than for everyday use - without it, a server quietly dropping to the older
protocol looks the same as one that never tried.

To hold a connection to one level and no other:

    Set LanMan98$SMB3 ""    SMB 3.0 and 3.0.2 only
    Set LanMan98$SMB2 ""    SMB 2.0.2 and 2.1 only
    Set LanMan98$SMB1 ""    the old protocol only, no SMB2 offered

Whichever is set is what gets used, or the connection fails saying why -
nothing falls back to something else and hides which level was the one that
worked.  That is what these are for; none is needed to connect normally.

LanMan98$SMB2 used to mean "try SMB2 first", which now happens without being
asked.  A machine that already sets it to reach a server needing SMB2 still
reaches it.


Reporting a problem
-------------------
    Set LanMan98$Log <a file>

writes an account of what the connection did into that file - what was
connected to, the dialect settled on, the transfer sizes offered and the
smaller ones used, every file opened with the size reported for it, every
read and write asked for, a line per message each way, and any error at the
moment it is raised, with its text and number.  Send that file.

It is more use than a packet capture when the complaint is that nothing
reaches the network: a capture of a file that opens and then will not read
simply stops, and cannot say whether the machine never asked for the data or
asked and was refused.  The log has both sides of that line in it.

It appends, so one file can hold several attempts, and it is flushed a line
at a time so a machine that stops dead still leaves everything up to the
point where it stopped.  It slows transfers down; set it to reproduce a
fault and unset it afterwards.


Finding servers
---------------
Choose "Discover" from the icon bar menu.  It asks the network what is on
it, asks each machine what it shares, and opens a directory of what it
found.  Double click one and the connect window opens with the server and
share already in it, wanting only a password.

What is found is not kept.  It goes in the scrap directory and is cleared
out at the start of the next look; a share becomes a permanent icon in
!LanMan98.Discs when it is double clicked and the connection succeeds.  A
share already kept there is left alone rather than offered again, so a
password saved in one is never thrown away.

The same thing from the command line:

    *Servers98              what is out there
    *Shares98 <server>      what one machine shares
    *Discover98             both, leaving the icons behind

A machine that refuses the name it is given is asked again without one, so
a machine nobody is logged on to still lists what it shares if it allows
guests - which is what guest sharing on a Mac is.  Leaving the user name
empty on the connect window does the same thing for a share.

Finding servers needs a network that carries a question addressed to
everybody.  Where it does not, LanMan98$DiscoverAddr names one machine to
ask instead.  Listing shares needs SMB2 - there is no way to ask a server
over the older protocol.


Signing
-------
A server that requires signed messages is signed to automatically, in
whichever protocol is in use, and needs nothing set up.  Signing is not used
otherwise: it costs a digest over every byte transferred, which on a slow
machine is a noticeable part of the transfer time and buys nothing on a
network you trust.  To sign anyway:

    Set LanMan98$Sign ""

A server that merely offers signing turns it on only for a client that asks
in the negotiate, which is what that does.

SMB 3.x signs with AES-CMAC and 2.x with HMAC-SHA256; which is used follows
whichever dialect the server picked, and needs nothing set.  Signing costs
real time on a slow machine - a sixty kilobyte transfer is a digest over all
sixty kilobytes - which is the reason it is not simply always on.


Settings
--------
!LanMan98.!Run lists them all, commented out, with a note on each.  None is
needed for ordinary use.


Unpacking
---------
This archive carries RISC OS filetypes, so unpack it on RISC OS - SparkFS,
SparkPlug and the RISC OS build of UnZip all read them - and everything
arrives correctly typed and dated.  Unpacking on a PC and copying across
loses the types: the module will not load and the Obey files will not run.
If you have to go that way, set the types by hand afterwards, or copy over
a LanMan98 mount with filetype mapping switched on.

TestSuite.Sources holds the two BASIC programs as readable text, for
reading or editing.  The suite runs the tokenised copies beside it.


Authorship
----------
LanMan98 is Copyright (c) Warm Silence Software Ltd 1996-2019, and the Open
Source Edition Copyright (c) RISC OS Developments 2019 onwards.  The original
author is Paul Gardiner.

The SMB2 support, the NTLMSSP authentication and the message signing added in
2.18 to 3.00 are Copyright (c) RISC OS Developments 2026, and the SMB2/3
changes are credited to the RISC OS One Project.
