Properties for Network interface

[Witold Sowa]

Marcel Holtmann pisze:
> Hi guys,
> 
Hi Marcel,

Sorry for a very late response. There was other stuff with API to clean
up at first, and then I needed to focus more on my studies. I have some
free time now, so lets clean the Network interface up.

> I am not sure about all possible security configuration, but in the end
> we can add them later on when needed. So lets start a proposal.
> 
> 	SSID		: array{byte}
> 	Mode		: string	("infrastructure" or "ad-hoc")
The "master" mode is missing here.

> 	Protocol	: string	("rsn", "wpa" or "")
> 	KeyMgmt		: string	(like in Capabilities)
> 	AuthAlg		: array{string}	(like in Capabilities)
> 	Pairwise	: array{string}	(like in Capabilities)
> 	Group		: string	(like in Capabilities)
> 	KeyIndex	: byte
> 	Key0		: array{byte}
> 	PSK		: array{byte}
> 	Priority	: byte
> 
I would add following properties here:
	Frequency	: uint16	(for master and ad-hoc modes)
	BSSID		: array{byte}	(NM uses it)
	ScanSSID	: boolean	(NM sets it to true)

and a bunch of EAP related properties (more about this at the end of
this mail).

> So the SSID and Mode are pretty clear I guess. I do prefer to have the
> SSID as byte array. Since that way we could actually match them up with
> the results BSSs. Converting a string into a hex SSID is always simpler
> than the other way around.
> 
Agreed.

> For Protocol and KeyMgmt, I am not sure if it would make sense to
> provide an array of possible option. I guess not. The "" in Protocol
> would allow to auto-detect RSN or WPA and that should be fine.
> 
Actually, I would prefer to have list of possible options then the
string with one option. At least for KeyMgmt property. It wouldn't be
any way painful for the clients, but it would give more configuration
options and keep API be more similar to config file. The empty array
would mean default setting.

> For Group, I assume we never have to provide a list of valid options. So
> just providing the group cipher or "" for automatic should be enough. In
> case of Pairwise, I am not sure how much useful it is to provide a list
> of valid option. Or just only allow one or "" for automatic.
> 
Same here. List of ciphers we are willing to use or and empty list to
let wpa_supplicant choose it (use default).

> The AuthAlg should support multiple options. I have used "OPEN SHARED"
> often to not have to bother with the details. And I think it is best to
> leave this up to wpa_supplicant or the kernel instead of having the
> client to figure this out. If not, then we could clearly make this a
> string.
> 
I think that list of options will be fine. We need to add "leap" option too.

> For the Key[1-4] and PSK we should use the hex version and the client
> has to convert them. I really dislike the magic with detecting that it
> is a string or not.
> 
I agree that for Key[0-3] (not [1-4]) we should use 5 or 13 bytes length
array. Clients could set ASCII or HEX keys easily since HEX key is just
numerical representation of its ASCII version.
Its a bit more complicated for PSK. We can have either fixed-length 32
bytes HEX key or 8 to 63 printable ASCII characters passphrase and
conversion between these formats isn't as simple as in case of WEP key.
We should have a possibility to set ASCII passphrase since in the most
cases users use this format and I don't see a point in forcing clients
to do conversion to 32-bytes HEX format since wpa_supplicant can do
this. In the other hand we should allow setting HEX key too because of
performance issues - ASCII->HEX conversion uses quite a lot of CPU.
I would suggest that Psk property should be a string containing either
8-63 characters of passphrase or 64 hex digits of 32-byte key.

> Some of these properties could be actually read-write when the network
> is not connected. For example Priority is a good candidate that might be
> changed at runtime.
> 
Yeah, most of properties would be read-write, but I believe that some of
them should be write-only because of security issues. I think that we
shouldn't expose any secret information like WEP keys or WPA psk over
DBus interface. Alternatively we could use methods like
SetWEPKey(keyId:byte, key:array{byte}) instead of write-only properties.
We could have SetWPAPassphrase(pass:string) and
SetWPAKey(key:array{byte}) methods then what would solve the problem
with Psk property type.

I think that we should return a DBus error like
fi.w1.wpa_supplicant.NetworkBusy if client tries to set a property of
already connected network. Alternatively we could allow setting of some
properties in already connected networks (which properties?).

There is a kind of problem what to do with properties which are not set
like Frequency in infrastructure mode, Psk in WEP networks or Key[0-3]
or KeyIndex in WPA networks. The problem is the most complicated for non
container type properties (i.e. not arrays or dicts). For not set Key or
Psk we could return empty array or empty string. But what with not set
KeyIndex or Frequency integers? I think that the best what we could do
would be to return DBus error like fi.w1.wpa_supplicant.PropertyNotSet,
but unfortunately we can't be always sure if property is set or not. Eg.
KeyIndex will be 0 if not set, but can be set to 0 as well.

As I mentioned earlier in this mail we need EAP configuration support in
Network DBus objects. Actually, I would consider putting EAP properties
in separate sub-interface like fi.w1.wpa_supplicant.Network.EAP. Here is
my proposition of properties which would cover config options that
NetworkManager uses now:

Methods			: array{string}	(like in EapMethods)
FragmentSize		: uint16
RequireWepKeys		: array{string}	("unicast", "broadcast")
Identity		: string
AnonymousIdentity	: string
Password		: string
Phase1PeapVersion	: byte		(0, 1)
Phase1PeapNewLabel	: boolean
Phase1FastProvisioning	: array{string}	("unauthenticated",
					 "authenticated")
Phase2Auth		: array{string}
Phase2AuthEap		: array{string}
CACert			: string
CAPath			: string
ClientCert		: string
PrivateKey		: string
PrivateKeyPassword	: string
Pin			: string
Phase2CACert		: string
Phase2CAPath		: string
Phase2ClientCert	: string
Phase2PrivateKey	: string
Phase2PrivateKeyPassword: string

The format of Password property is the same as in the config file (i.e.
string in plain text or NtPasswordHash in format hash:32-hex-digits)

*Cert and *Path properties are file paths to cert files or pointers to
previously set blobs in format blob://blob-name.

I would consider some of above properties to be secret and make them
write-only.

This proposal covers more then half of network config options that
wpa_supplicant and I believe that with some effort we would be able to
expose almost all of them via the DBus interface.

Any thoughts?
I hope that I didn't bored you with this lengthy email.

Regards,
Witek.