Local DWS APIs
Local access (i.e., access over the local network) of the Diagnostic Web Server (DWS) is disabled by default as of BrightSignOS 9.0.218 (on the 9.0 branch) and BrightSignOS 9.1.75 (on the 9.1 branch). In BrightSignOS versions prior to these, local access to the DWS was enabled by default. To enable local access to the DWS, see DWS: Local AccessDWS: Local Access.
Note that some specially configured players have the external microSD card port and USB storage disabled at the factory (SKU: SVC-internal-storage-only). For these players, local access to the DWS remains enabled by default.
Remote access (i.e., access over the internet) of the DWS remains available for all internet-connected players registered with BrightSign Cloud.
There are two ways to access these APIs:
- You can choose to use digest authentication. Digest authentication uses a username and a password. The username is always “admin”. The password can be set in three ways:
- Use the default, which is the player serial number
- Set it through the setup package
- Set it using a custom script
- You can choose to use no authentication. However, this is not recommended.
Once the password is set, you need to authenticate to access the Local DWS APIs. To do this:
- You should be using BrightSignOS 8.4.6 or newer.
- Call the desired API using digest authentication with the Local DWS username and password. Note that digest authentication is fairly insecure when used over an insecure transport (HTTP).
The URL prefix is always https://player_ip/api
API Definitions
The listed APIs are prefixed with the version /v1. We can not guarantee that these documents will be current in every case.
Using HTTPS with the Local DWS
In BOS releases after BOS 8.2.35.4, users had the option use either a trusted certificate or a self-signed certificate to access HTTPS over the DWS. As of BOS 9.0.218 and 9.1.52, the Local DWS uses HTTPS by default with a self-signed certificate. Previously (in BOS 8.2.35.4 and newer) HTTPS was optional, but a self-signed certificate had to be provided. See Add Digital Certificates for information about how to apply a certificate to a player.
If your existing scripts use HTTP to access LDWS, you should update them to use HTTPS. If updating the scripts is not immediately possible, you may temporarily set the enable_http_redirect registry key in the networking section to false (link to the registry doc). This disables HTTP redirection, allowing your current scripts to continue functioning.
Please note that HTTPS is enforced regardless of the registry key setting. The registry key only controls HTTP redirection behavior and does not disable HTTPS enforcement.
Generating a Self-Signed Certificate and Key
To do this, choose one of the following two methods:
- Run this code:
openssl req -nodes -new -x509 -keyout dws.key -out dws.crt- OR run the following code and use the 'dws.key' and 'dws.crt' files. The other files can be deleted later.
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
openssl genrsa -out dws.key 4096
openssl req -new -key dws.key -out client.req
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out dws.crtMaking the Certificate and Key Files Accessible
The operating system will look for files with known names at the root of the default storage. To make the certificate and key files you generated findable, either:
- Name the files dws.crt and dws.key, as in the examples.
- Put the names of the files in the networking registry using the keys ldws_cert_file_name, ldws_key_file_name. See BrightSign Registry Keys for more information.
If you want to supply the CA certificate, you can use the default name dws.ca or if you want to use another name use the registry key ldws_ca_file_name to specify the filename.
Then put the files at the root of the default storage. If you have defined the ldws_certs_path registry key, this will be the certs location (rather than the default storage).