Trying to wrap my head around FreeRadius config

[Moe, John]

> -----Original Message-----
> From: freeradius-users-bounces+jmoe=hatch.com.au at lists.freeradius.org
> [mailto:freeradius-users-
> bounces+jmoe=hatch.com.au at lists.freeradius.org] On Behalf Of Phil
> Mayers
> Sent: Tuesday, 19 July 2011 5:10 PM
> To: freeradius-users at lists.freeradius.org
> Subject: Re: Trying to wrap my head around FreeRadius config
> 
> On 07/19/2011 05:20 AM, Moe, John wrote:
> 
> > 1) When a RADIUS request gets received by the server, it first looks
> up
> > the device in the clients.conf file.  If it doesn't exist there, it
> > ignores the request (with a message being logged saying it ignored
> the
> > request).
> 
> More or less.

Well, I wasn't intending to write a full process-flow for this, I was
trying to get the basics down first. :-)

> The full version goes as follows:
> 
>   1. Packet is received on a socket
>   2. FreeRADIUS looks up the "clients" for the corresponding "listen {
> }" section, or the corresponding virtual server, or the global clients
> if both those unset
>   3. It gets the shared secret for the client
>   4. If present, it verifies the Message-Authenticator, dropping the
> packet if invalid

I didn't realize that FreeRadius did anything with the
Message-Authenticator.  Good to keep in mind.

> >
> > 2) If it has the client listed in clients.conf, it then runs the
> request
> > through the sites-enabled/default file.  That file seems to say,
> > starting with the authorize section, run it through the preprocess
> > module, then chap, mschap, suffix, eap, unix, files, expiration,
> > logintime and finally, pap.
> 
> Again, more or less.
> 
> It actually runs the request through whatever virtual server is
> specified in the clients or listen block, or "default" if unset.
> 
> And yes, it processes through the modules one at a time. See
> doc/configurable_failover for more info.
> 
> >
> > This is where things start to get a bit blurry for me.  I understand
> > that the preprocess module is rlm_preprocess, and that the config
> lives
> > in modules/preprocess, where I can read a description of that module
> and
> > what it does.  Likewise for chap and mschap.  However, suffix
doesn't
> > appear to be a module; where'd this come from, and what does it do?
> 
> "suffix" is a named instance of the "realm" module; see modules/realm.

Ah, I'd wondered how the named instances of a module get called; now I
know.

> Basically, you can have >1 instance of a module with different config
> e.g.
> 
> realm suffix {
>   ...
> }
> 
> 
> In 2.x, the "unlang" feature of the server also allows you to write
> "conditional" statements that internally are just modules in the
> processing list, like so:
> 
> if (User-Name == foo) {
>    sql2
> }
> # note "else" must be on it's own line
> # because it's a module, see - line-based
> else {
>    sql1
> }
> 
> ...which is a series of 2 modules - an "if" module, an "else" module
> (that only runs when the "if" doesn't) and their child module(s).
> 
> It's all just modules though; all the way down.
> 
> > There also appear to be some modules in /usr/lib64/rlm_* that appear
> to
> > have neither a man page, nor a config file in the modules directory,
> nor
> > any sort of description in the Configuration Files section of the
> Wiki
> > page.
> 
> Possibly. Which ones, specifically?

Well, I didn't have any one in mind.  I was just wondering if there was
more documentation that I'd missed, and might read up on later, that
would give me other modules that would prove useful.  Looking back
through it now, though, I'm wondering what I was interested in, to be
honest.  Skip it.

The exception to this is the rlm_eap_* modules, but I think they're
covered by the eap.conf file, right?

> >
> > 3) The chap, mschap and eap modules seem to all look at the request
> and
> > decide if the request is using any of these.  If so, they add "Auth-
> Type
> > :=<one of them>" to the config item list.  The eap module isn't
> 
> Correct
> 
> > configured under the modules directory, but in the root directory in
> > eap.conf, the others in their respective file in the modules
> directory.
> 
> Yes, that's historical. In the 3.x versions of the server, the default
> "eap" module config lives in modules/eap.

Ah, I was under the impression from my reading that it used to be in the
modules folder, but was large and important enough to break out for some
reason. I guess I got the wrong impression.

> >
> > 4) Given the information in the config items, it tries match the
> request
> > against the unix and files modules, and add/modify config items
> > appropriately.  The "files" module is configured by default to read
> in
> > the entries from the users file, where I should add "DEFAULT"
entries
> to
> > match the various types of authentication and authorization I'm
> trying
> > to configure.  In there, if it matches against any ruleset, it adds
> the
> > reply items to the request.
> 
> Sort of. Your terminology is a bit confusing.

Which is part of the reason for my questions, so I can learn it
properly. :-)

> *All* modules work by matching & modifying 3 lists of variables:
> 
>   1. request - came from the client
>   2. config - internal to the server
>   3. reply - sent back to the client
> 
> Ignoring the "unix" module (which isn't generally that useful) the
> "files" module basically does this:
> 
>   1. Expands the "key" variable (defaults to "%{User-Name}")
>   2. Walk through the entries in the file as follows:
>      * If key matches or key==DEFAULT, process entry
>        If Fall-Through = yes, proceed to next entry
> 
> The entry process basically works as follows:
> 
>   * All compare/set operations are on the 1st line
>   * Compare operations are made against request variables
>   * Set operations are made against check/control variables
> 
> e.g. in the "users" file, this:
> 
> DEFAULT	Foo == "bar", Baz := "ban"
> 
> ...means: compare Foo in the request against "bar"; if it matches set
> "Baz" in the control items to "ban"
>
> >
> > 5) It then runs the config items against the expiration and
logintime
> > modules, which checks the Expiration attribute and some Time
> attributes
> > for authorization limitations.
> 
> What is "It" in this sentence?

"It" = the FreeRadius server.  And I guess "against" isn't the right
word, probably "through" would be better.

> The modules themselves do the comparison.
> 
> >
> > 6) It finally runs it through the PAP module to see if it's a PAP
> > request, and adds "Auth-Type := PAP" to the config items.
> 
> Again, the "pap" module does this
> 
> >
> > Where do the rest of the attributes that get sent with the packet
get
> > added to the config item list?  Does that happen first?  Does that
> > happen later?  Or is the incoming request with all its attributes
> > immediately turned into a list of config items?  None of the modules
> > listed seem to say they parse the request and add the request's
> > attributes to the config items.
> 
> They don't. That doesn't happen.
> 
> Each radius request has 3 lists:
> 
>   1. Request - populated initially with the AVPs from the packet
>   2. Config/control - initially empty
>   3. Reply - initially empty
> 
> The request variables don't get copied to config/control; that
wouldn't
> make sense. They're control variables after all.
> 
> Modules are expected to populate the "control" list. The core
"control"
> attributes that matter are:
> 
>   1. Cleartext-Password - expected to be set in the "authorize"
section
> by one of the "database" or "lookup" modules (e.g. SQL, LDAP). Used
> later to in the "authenticate" section by "pap", "mschap" etc.
> 
>   2. XXX-Password - same as above, but various types of password hash
> that are compatible with the authentication module; e.g. NT-Password
> for
> "mschap", Crypt-Password for PAP
> 
>   3. Auth-Type - set by the relevant module to "itself" in
"authorize";
> used to "re-run" the module in "authenticate" after the various
> database
> modules have had a chance to add XX-Password
> 
>   4. Proxy-To-Realm - set by the "realm" module, or manually. Used to
> proxy the request. Stops "authenticate" being run.
> 
> There are various others, but those are the main ones.

So then, when matching an entry in "users", does it look at the request
items, or the config items?  When creating an entry, you specify first
things to match against on one line separated by commas, and then reply
items, each on its own line, separated by commas.  Those things to match
against, do they match the request items or the config items?  I'm
trying to understand the difference between request and config.

> >
> > After all this, it then runs through the authenticate section of the
> > sites-enable/default file, where it does the user/password checking:
> >
> > 1) It checks to see if the Auth-Type is PAP, CHAP, or MS-CHAP, and
> then
> > runs them through the appropriate module.
> >
> > 2) It runs the request through the unix module
> >
> > 3) It runs it through the eap module (again, configured in eap.conf)
> 
> Yeah, that's all a bit confusing and historical. Basically the
> "authenticate" section just works; don't worry about it too much.
> Provided you don't fiddle with Auth-Type, the right module will be
run.
> 
> >
> > At some point, (I believe in both the authorize and authentication
> > sections, in the eap module), if it finds that a request is using
> PEAP,
> > it does much the same thing again, but runs the inner
> > "data/packet/encryption/not sure what to call it here" through the
> > sites-enabled/inner-tunnel file, with sections set up similarly to
> the
> > sites-enabled/default file.
> 
> Not quite. EAP is a multi-packet challenge/response mechanism; PEAP in
> particular basically tunnels TLS over radius, then the "inner" auth
> over
> TLS. So the packet flow is as follows:
> 
>   1. Access-Request from client with TLS inside EAP-Message
>   2. Access-Challenge from server with TLS
>   3. Repeat 1/2 several times until TLS is setup
>   4. Access-Request from client with TLS payload inside EAP-Message
>      a. payload decrypted and turned into a fake radius packet
>      b. fake packet sent to "inner-tunnel" virtual server
>      c. reply comes back - maybe Access-Challenge or Access-Accept
>      d. reply turned back into TLS payload
>   5. Access-Challenge from server with TLS payload
>   6. Repeat 4/5 until inner-tunnel succeeds with Access-Accept
>   7. Access-Request from client with TLS "PEAP success" payload
>   8. Access-Accept from server
> 
> ...all the numbered steps run in the "outer" server. All the lettered
> steps run in the "inner" server.
> 
> For extra fun, steps 4/5 in the outer server make the "eap" module
> return "ok" in the "authorize" section, which allows you to stop
> processing the rest of the "authorize" section, because you know you
> don't need to - it'll all happen in the inner-tunnel.

... I think I'm going to need to re-read this a few times and play with
it on my server to fully get this part. I thought TLS was only one
mechanism within PEAP that it could use; another, for example, is
MSCHAPv2 (which is what I'm going to be using).  Or does it use TLS on
the PEAP portion to set up the outer tunnel, regardless of what's used
inside?

> > Then there are the session and post-auth sections, that I haven't
> even
> 
> post-auth is run for the final Access-Accept or Access-Reject. It
> allows
> you to do things which only need to be done on the final packet. For
> example, really post-auth is where the vlan assignment lookup should
be
> run - though a lot of people do it in "authorize" for various reasons,
> this can lead to >1 "database" lookup for multi-pass radius exchanges
> e.g. EAP.

I'll have to have a closer look at this then; it's one of the intended
uses I have for this.

> session is for Simultaneous-Use; I've never used it, so never bothered
> to figure out how it works.
> 
> 
> Really something like the above info should live in the wiki. The
> request processing pipeline is a common question.
> -
> List info/subscribe/unsubscribe? See
> http://www.freeradius.org/list/users.html

Thanks so much for your response, it's cleared up a few things and
helped me along.  I'm sure more questions will pop up as I re-read both
this and the reply from Alan DeKok (which I'm going to reply to
separately), and continue to work on this; I'll repost individual,
hopefully smaller, questions when they arise.


John H. Moe
Network Support - Hatch IT
HATCH
Tel: +61 (7) 3166 7777
Direct: +61 (7) 3166 7684
Fax: +61 (7) 3368 3754
Mobile: +61 438 772 425
61 Petrie Terrace, Brisbane, Queensland Australia 4011
*****************************
NOTICE - This message from Hatch is intended only for the use of the individual or entity to which it is addressed and may contain information which is privileged, confidential or proprietary. 
Internet communications cannot be guaranteed to be secure or error-free as information could be intercepted, corrupted, lost, arrive late or contain viruses. By communicating with us via e-mail, you accept such risks.  When addressed to our clients, any information, drawings, opinions or advice (collectively, "information") contained in this e-mail is subject to the terms and conditions expressed in the governing agreements.  Where no such agreement exists, the recipient shall neither rely upon nor disclose to others, such information without our written consent.  Unless otherwise agreed, we do not assume any liability with respect to the accuracy or completeness of the information set out in this e-mail.  If you have received this message in error, please notify us immediately by return e-mail and destroy and delete the message from your computer.