Page Comparison

...

Some of the settings are specific to the network interface, while others are used by the BrightSign host for all network interfaces.

BrightSign players support most commonly used wireless encryption formats: WEP (64 & 128), WPA (TKIP), and WPA2 (AES). WPA Enterprise is also supported using DER, PEM, or PKCS#12 certificates. Wired authentication via 802.1x is not supported for WPA/WPA2 Enterprise, nor are other modes such as PEAPv0/MSCAPv2.

ifNetworkConfiguration

Apply() As Boolean

...

Enables or disables the Ethernet activity LED (i.e. flashing during link and activity behavior). The Ethernet LED is enabled by default. Changes to this setting do not persist across reboots. This method returns true upon success and false upon failure. Note that this method is not available on HDx10, HDx20, and LSx22 models.

...

SetClientIdentifier(

...

a As String

...

SetClientIdentifier(a As String) ) As Boolean

Sets the DHCP client identifier.

...

Sets EAP-specific options. Currently, this method can be used to enable or disable MD5 support ("md5=enable" or "md5=disable") and to set an anonymous identity for EAP-PEAP/MSCHAP configurations ("anonymous_identity=anon@brightsign.biz"). Multiple parameters can be set with a space-separated list. To clear previous settings, pass an empty string to this method.

SetWiFiCACertificates(certificates As Dynamic) As Boolean

...

Note

title	Note

If the client certificate and associated private key are in the same PKCS#12 file, the file contents should be specified using the SetWiFiPrivateKey() method and the SetWiFiClientCertificate() value should be left empty.

...

SetWiFiSecurityMode(

...

mode As

...

String) As Boolean

Configures a DHCP server on the wireless access point. The associative array should consist of two properties: ip4_start, which specifies the beginning of the range of offered IP addresses, and ip4_end, which specifies the end of the range. To disable the DHCP server, pass an empty associative array ({}) to this method. This method returns true on success and false on failure; use the GetFailureReason() method to return information in case of failure.

SetDomain(domain As String) As Boolean (host)

Sets the device domain name. This will be appended to names to fully qualify them, though it is not necessary to call this. This method returns true on success.

Code Block

title	Example

nc.SetDomain("brightsign.biz")

...

Sets the encryption to use for WPA Enterprise authentication. By default, both WPA (TKIP) and WPA2 (CCMP) encryption are permitted. This method accepts a space-separated, case-insensitive list that can include either "tkip" or "ccmp" values. Passing an empty string sets the default mode. If both CCMP and TKIP are allowed, CCMP always has priority.

ConfigureDHCPServer(config As roAssociativeArray) As Boolean

Configures a DHCP server on the wireless access point. The associative array should consist of two properties: ip4_start, which specifies the beginning of the range of offered IP addresses, and ip4_end, which specifies the end of the range. To disable the DHCP server, pass an empty associative array ({}) to this method. This method returns true on success and false on failure; use the GetFailureReason() method to return information in case of failure.

SetDomain(domain As String) As Boolean (host)

Sets the list of DNS servers if there were no DNS servers device domain name. This will be appended to names to fully qualify them, though it is not necessary to call this. This method returns true on success.

Code Block

title	Example

nc.SetDomain("brightsign.biz")

SetDNSServers(servers As roArray) As Boolean (host)

Sets the list of DNS servers if there were no DNS servers when the object was created. This method accepts an array of strings, each containing the dotted-quad IP address of a DNS server, and it returns true on success. There is currently a maximum of three servers; the method will return false if you attempt to add more than three servers.

...

Sets the name or address of the proxy server used for HTTP and FTP requests. The proxy string should be formatted as "http://user:password@hostname:port". The hostname can contain up to four "*" characters; each "*" character can be used to replace one octet from the current IP address. For example, if the IP address is currently 192.168.1.2, and the proxy is set to "proxy-*-*", then the player will attempt to use a proxy named "proxy-192.168".

...

GetProxy(

...

) As

...

String (host)

...

Returns the name or address of the proxy server.

SetProxyBypass(hostnames As Array) As Boolean

Exempts the specified hosts from the proxy setting. The passed array should consist of one or more hostnames. The player will attempt to reach the specified hosts directly rather than using the proxy that has been specified with the SetProxy() method. For example, the hostname "example.com" would exempt "example.com", "example.com:80", and "www.example.com" from the proxy setting.

...

Value	Type	Description
essid	String	Network name
bssid	String	Access point BSSID
signal	Integer	Received signal strength indication. The absolute value of this field is not usually relevant, but it can be compared with the reported value on other networks or in different locations.

Network Authentication

BrightSign players support most commonly used wireless encryption formats: WEP (64 & 128), WPA (TKIP), and WPA2 (AES).

WPA Enterprise is supported using EAP-TLS (with DER, PEM, or PKCS#12 certificates) and PEAPv0/MSCHAPv2 (with a username and passphrase). Wired authentication via 802.1x is also supported. The configuration instructions below apply to both WiFi and wired authentication via 802.1x; the only difference is the wired/wireless parameter (0/1) passed during roNetworkConfiguration initialization.

EAP-TLS

EAP-TLS authentication requires a client certificate and private key. There are two ways to accomplish this:

Packaging the client certificate and private key in a single file in PKCS#12 format (using PEM or DER encoding), usually with a .p12 file extension. To do this, set the PKCS#12 file using the SetWiFiPrivateKey() method and pass a blank string to the SetWiFiClientCertificate() method.
Packaging the client certificate as a X.509 certificate (using PEM or DER encoding) and using a passphrase to secure the key (instead of the usual WiFi passphrase). To do this, set the client certificate using the SetWiFiClientCertificate() method and the key using the SetWiFiPrivateKey() method. You can then optionally call SetWiFiPassphrase() to protect the key with a passphrase.

Certificate keys may contain binary data if not PEM formatted. In this case, they must be provided as an roByteArray object. Text formats may be passed using a string or roByteArray.

Code Block

title	Example: Setting EAP-TLS with a .p12 file

nc = CreateObject("roNetworkConfiguration",1)
 
p12 = CreateObject("roByteArray")
p12.ReadFile("client.p12")

nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey(p12)
nc.SetWiFiPassphrase("passwordgoeshere")

During authentication, the Radius server is passed an identity. By default, the identity will be taken from the client certificate. If the certificate has a "subjectAltName", it will be used; otherwise, the "CommonName" is used. If neither of these are correct, the identity may be overridden. This default behavior can be overridden by calling SetWiFiIdentity(), and it can be restored by passing a blank string to SetWiFiIdentity().

PEAP/MSCHAP

This mode requires an identity (username) and passphrase, rather than a client certificate. There may also be a second, "outer", identity–see the Special Cases section below for configuration details.

Code Block
nc = CreateObject("roNetworkConfiguration",1) nc.SetWiFiIdentity("user@brightsign-example.com") nc.SetWifiPassphrase("passwordgoeshere")

COMMON VARIANTS

Additional Certificates

Additional CA certificates are often required (and using a custom CA for authentication is potentially more secure). Also, some CA hierarchies require intermediate certificates. CA certificates are sometimes supplied via EAP, but if the server does not supply them, they may be added to the CA file using the SetWiFiCACertififcates() method. This method supports PEM and DER certificates.

Code Block
nc = CreateObject("roNetworkConfiguration",1) ca = CreateObject("roByteArray") ca.ReadFile("ca.pem") nc.SetWiFiCACertificates(ca)

Obfuscated WiFi Passphrase

If an obfuscated WiFi passphrase is required, you can substitute the SetObfuscatedWiFiPassphrase() method for the SetWiFiPassphrase() method. Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.

TKIP/CCMP Encryption

By default, both WPA (TKIP) and WPA2 (CCMP) encryption is permitted. You can alter this behavior using the SetSecurityMode() method, which accepts a space-separated, case-insensitive list of allowed modes ("ccmp" and "tkip"). If both CCMP and TKIP are allowed, CCMP always has priority.

Code Block

nc = CreateObject("roNetworkConfiguration",1)
nc.SetWiFiSecurityMode("") 'Sets the default mode
nc.SetWiFiSecurityMode("ccmp tkip") 'Explicitly allows both modes (same as the default mode)
nc.SetWiFiSecurityMode("ccmp") 'Requires the use of CCMP

SPECIAL CASES

MD5 Support

MD5 support is enabled by default for backwards-compatibility reasons. This behavior can be modified by passing the "md5=enable" or "md5=disable" string to the SetWiFiEapTlsOptions() method.

Code Block
nc = CreateObject("roNetworkConfiguration",1) nc.SetWiFiEapTlsOptions("md5=disable")

Anonymous Identity

Some EAP-PEAP/MSCHAP configurations require an anonymous identity. By default, the BrightSign player uses the same inner and outer identity. An anonymous identity can be configured with the SetWiFiEaptTlsOptions() method:

Code Block
nc = CreateObject("roNetworkConfiguration",1) nc.SetWiFiEapTlsOptions("anonymous_identity=anon@brightsign.biz")

Tip

title	Tip

If neither MD5 or identity options are being used, the setting should be cleard by passing a blank string to the SetWiFiEaptTlsOptions() method.

Validity Dates

Validity dates are required for both EAP-TLS and PEAP/MSCHAP. The current time is required to check the certificate. If the player clock has not been set, it will typically set its time using the network, but this requires EAP authentication first. To avoid this problem, there are two special exceptions:

EAP-TLS: When the clock is not set, the time is set to ten seconds after the client certificate becomes valid, which is usually sufficient to authenticate (though this may not be sufficient for servers with newer certificates than the client).
PEAP/MSCHAP: There is no client certificate, so the certificate time is not checked when the date is not set.

The clock can also be set via the Diagnostic Web Server, which prevents either of the above exceptions from being used. Typically, the clock is also set from the network once it is available, so these exceptions are only used on first boot or when the clock battery has been completely emptied.

Examples

The following script disables WPA Enterprise configuration (which is otherwise persistent):

Code Block

nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiSecurityMode("")
nc.SetWiFiESSID("")
nc.SetWiFiIdentity("")
nc.SetWiFiCaCertificates("")
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey("")
nc.SetWiFiPassphrase("")
nc.SetWiFiEapTlsOptions("")
ok = nc.Apply()

The following script configures the WiFi for EAP-TLS using a PKCS#12 (.p12) file, without additional CA certificates:

Code Block

essid = "brightwifi"
pkcs12file = "client.p12"
pkcspass = "passwordgoeshere"

nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiESSID(essid)

p12 = CreateObject("roByteArray")
ok = p12.ReadFile(pkcs12file)

if ok then
    nc.SetWiFiClientCertificate("")
    nc.SetWiFiPrivateKey(p12)
    nc.SetWiFiPassphrase(pkcspass)

    nc.SetWiFiCaCertificates("")
    nc.SetWiFiSecurityMode("")
    nc.SetWiFiIdentity("")
    nc.SetWiFiEapTlsOptions("")

    ok = nc.Apply()
end if

The following script configures the WiFi for EAP-TLS with additional certificates:

Code Block

essid = "brightwifi"
cafile = "cacert.pem"
pkcs12file = "client.p12"
pkcspass = "passwordgoeshere"

nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiESSID(essid)

p12 = CreateObject("roByteArray")
ok = p12.ReadFile(pkcs12file)

ca = CreateObject("roByteArray")
ok = ca.ReadFile(cafile) and ok

if ok then
    nc.SetWiFiClientCertificate("")
    nc.SetWiFiPrivateKey(p12)
    nc.SetWiFiPassphrase(pkcspass)

    nc.SetWiFiCaCertificates("")
    nc.SetWiFiSecurityMode("")
    nc.SetWiFiIdentity("")
    nc.SetWiFiEapTlsOptions("")

    ok = nc.Apply()
end if

The following script configures the WiFi for PEAP/MSCHAP with additional CA files:

Code Block

essid = "brightwifi"
cafile = "ca.pem"
user = "someuser@brightsign.biz"
pass = "whatever"
ca = CreateObject("roByteArray")
ok = ca.ReadFile(cafile)

if ok then
    nc = CreateObject("roNetworkConfiguration", 1)
    nc.SetWiFiESSID(essid)
    nc.SetWiFiIdentity(user)
    nc.SetWiFiPassphrase(pass)
    nc.SetWiFiCaCertificates(ca)
    nc.SetWiFiClientCertificate("")
    nc.SetWiFiPrivateKey("")
    'Use this if an anonymous outer identity is required
    'nc.SetWiFiEapTlsOptions("anonymous_identity=anon@brightsign.biz")
    nc.SetWiFiEapTlsOptions("")

    ok = nc.Apply()
    if not ok then
        fail = "Unable to set configuration: " + nc.GetFailureReason()
    end if
else
    fail = "Unable to read file " + cafile
end if

' if not ok, do something with the failure message

Versions Compared

Old Version 31

New Version 32

Key

ifNetworkConfiguration

Apply() As Boolean

SetClientIdentifier(

a As String

SetClientIdentifier(a As String) ) As Boolean

SetWiFiCACertificates(certificates As Dynamic) As Boolean

SetWiFiSecurityMode(

mode As

String) As Boolean

SetDomain(domain As String) As Boolean (host)

ConfigureDHCPServer(config As roAssociativeArray) As Boolean

SetDomain(domain As String) As Boolean (host)

SetDNSServers(servers As roArray) As Boolean (host)

GetProxy(

) As

String (host)

Returns the name or address of the proxy server.

SetProxyBypass(hostnames As Array) As Boolean

Network Authentication

EAP-TLS

PEAP/MSCHAP

COMMON VARIANTS

Additional Certificates

Obfuscated WiFi Passphrase

TKIP/CCMP Encryption

SPECIAL CASES

MD5 Support

Anonymous Identity

Validity Dates

Examples