---
title: Add Digital Certificates
slug: manage/add-digital-certificates
docTags: 
createdAt: 2025-03-11T06:58:09.587Z
---

BrightSign players use digital certificates to ensure secure connectivity and content delivery. Players use **client certificates** to authenticate to secure networks over Wi-Fi or Ethernet. To interact with secure websites (e.g., displaying web pages via HTTPS), players rely on **root CA certificates** to verify server certificates. These certificates are issued by trusted Certificate Authorities (CAs), ensuring robust security for both network authentication and web interactions.

# Client Certificates

In order to access a secure network, whether wireless (e.g., Wi-Fi) or wired (e.g., Ethernet), players need to provide authentication. A client certificate is a digital certificate issued to a player to authenticate its identity to a network or server. Players use client certificates to prove their identity to secure Wi-Fi (e.g., WPA2/WPA3-Enterprise with EAP-TLS) or Ethernet networks.

While players do offer the ability to use password-based network authentication, many customers prefer using client certificates, not only because of the added security, but also for their ability to provide network revocation of specific players. With a password-based authentication system, network access revocation of specific players is not possible since changing the password necessarily affects all players using that password.

Client certificates are typically issued by an organization's IT department and can be applied to players using either BrightSign Author or the BrightScript scripting language.

# Root CA Certificates

A root CA certificate is the top-level certificate in a CA’s trust chain, issued by a root CA. They can be installed on players to establish trust for certificates signed by that CA. Players typically use a root CA certificate to verify the identity of a secure website’s server certificate in order to display the website's content and/or to enable encrypted communication between the player and server.

Root CA certificates can be added to players using either the BrightSign Author app or the BrightScript scripting language. BrightSign partners who operate their own Content Mangement Systems (CMS) must include the ability to manage these types of certificates. 

# Certificate Format

The BrightSignOS uses NSS for all certificates and supports the PEM format type. Our current version is 3.51.1 and it is sourced from [this location](http://ftp.mozilla.org/pub/security/nss/releases/NSS_3_42_1_RTM/src/nss-3.42.1.tar.gz). Note that your OS or browser may indicate that this file cannot be downloaded securely. This is only a warning and you can choose to "keep" the file:

::Image[]{src="https://app.archbee.com/api/optimize/0prk6SO2dy9LdU77jB8D1/SbqGTrfr1pCSeDzRs0dkx_image.png" size="40" width="570" height="400" position="center" darkWidth="570" darkHeight="400" showCaption="false"}

Inside the NSS 3.42.1 package, the certs data is located at: `nss/lib/ckfw/builtins/certdata.txt`

# Adding Certificates

Both client and Root CA certificates can be added using either the BrightSign Author app or by using BrightScript to access the player's APIs. The easiest way to do this is through the app, as coding in BrightScript requires a higher level of technical skill.

## BrightSign Author

To add a certificate to a player using the BrightSign Author app, follow the steps below:

::::WorkflowBlock
:::WorkflowBlockItem
Obtain the necessary certificate. The info on [this page](https://gist.github.com/mtigas/952344) may be useful in converting certificates to the proper format and/or concatenating multiple certificates into a single, combined file.
:::

:::WorkflowBlockItem
Add the certificate to a Setup File. For more info about Setup Files, refer [here](https://docs.brightsign.biz/user-guides/setup).

1. From **Admin > Setup**, click **Network Configuration > Network Options**.
2. If adding a Root CA certificate, select the **Player** tab and go to the **Certificates** section. If adding a client certificate, select the **Wired** or **Wireless** tab depending on your network type, and go to the **Security** section:


::Image[]{src="https://api.archbee.com/api/optimize/0prk6SO2dy9LdU77jB8D1/csNfo5NGrLGP-27aVEIZu_image.png" size="60" width="713" height="715" position="center" caption="Adding a root CA certificate" darkWidth="713" darkHeight="715" showCaption="true" indent="2"}

::Image[]{src="https://api.archbee.com/api/optimize/0prk6SO2dy9LdU77jB8D1/lVt-Smdaj3-7Hn-l4LPN6_image.png" size="60" width="713" height="715" position="center" caption="Adding a client certificate for a wired network" darkWidth="713" darkHeight="715" showCaption="true" indent="2"}

::Image[]{src="https://api.archbee.com/api/optimize/0prk6SO2dy9LdU77jB8D1/FCU_dENS5-UELZbNn9s0d_image.png" size="60" width="713" height="715" position="center" caption="Adding a client certificate for a wireless network" darkWidth="713" darkHeight="715" showCaption="true" indent="2"}

3. Enter the relevant certificate info.
4. Select **Done** and **Save Setup** to save the Setup File.
:::

:::WorkflowBlockItem
Save the Setup File to a storage device (e.g., microSD card).
:::

:::WorkflowBlockItem
Install the storage device to the player.
:::
::::

:::hint{type="warning"}
There is unfortunately no way to modify certificates over the network. The only way to modify the certificate(s) is to repeat the above process.
:::

### Self-Signed Certificates

There may be situations where it is desired for players to use self-signed certificates (i.e., certificates not issued by a CA but instead created and signed by the user themselves). Since self-signed certificates are not widely trusted, they are typically used only in testing or controlled environments.

The BrightSign Author app can be used to apply self-signed certificates to players through the use of a [plugin](https://github.com/brightsign/BrightAuthor-Plugins/tree/master/Add-Client-Certificates).

## BrightScript

Certificates can also be added to player using the BrightScript scripting language, although this requires more technical skills.

- Users can install an unsigned certificate package through [roKeyStore](docId\:GhSZNW9eS8TEMURQXq-DU) (or [keystore](docId:6Alp0AIXrZlHV4cBkebvz)), [AddClientCertificate](docId\:GhSZNW9eS8TEMURQXq-DU) or [AddCACertificate](docId\:GhSZNW9eS8TEMURQXq-DU) before accessing the resource.
- The [roKeyStore](docId\:GhSZNW9eS8TEMURQXq-DU) (or [keystore](docId:6Alp0AIXrZlHV4cBkebvz)) objects allow users to register client certificates with the player. In roKeystore, use [AddCAPackage](docId\:GhSZNW9eS8TEMURQXq-DU) to install persistent *.bsca* packages.
- A .*bsca* file is required if the client is using an HTTPS URL with a certificate signed by a non-public root or intermediate for recovery, because there’s no way to add the certificate before the recovery URL is accessed. This is also true when an HTTPS proxy is used and that proxy uses internal/self-signed certificates. HTTPS URLs using certificates the player already trusts are okay, as long as the player’s clock is set so certificate selection can happen.

To confirm that the .*bsca* file is installed, check the system log for the .*bsca* file name which will appear there when it has been added. You can also download the installed CA certificates .*pem* file by entering your IP address in a web browser (*http\://\{\{ip\_address}}/ca\_certificates*). Add a .*pem* or .*crt* extension to open it in Windows. You can also use utility like [OpenSSL](https://www.openssl.org/) to inspect it.

# Unsigned Certificate Limitations

When the certificate is not signed and permanently installed, the certificate file will need to be on the microSD card which could have security implications. When a signed certificate is installed, it cannot be recovered from storage in a usable form and can be removed from the microSD card.

Unsigned certificates do not persist if a player reboots.

# Per-Access Certificates vs. Semi-Permanent Certificates

:::hint{type="info"}
BrightSign recommends that you use a per-access certificate unless you have a CMS that requires HTTPS that cannot be publicly validated.
:::

## Per-Access Certificates

This defines a client certificate for a specific HTTP widget.  Specific code needs to be run to load the certificate when creating the HTML widget, so this must be "enabled" in the content management system through an option or plugin. You can manage changes to these certificates without BrightSign intervention, but you may need CMS intervention depending on how your system handles certificates.

The disadvantage to per-access certificates is that because the client certificate is loaded at runtime, early processes like recovery, and processes that run outside of the CMS client runtime like device setup cannot use the client certificate so there must be a non-HTTPS link to the server for setup.

## Semi-Permanent Certificates

A .bsca certificate package can be semi-permanently installed on a player, and will apply to all player functionality, so recovery and other processes will work as long as the player has the .bsca package installed. The disadvantages are:

- BrightSign must sign the certificate package into a .bsca that can be installed on the player.
- If the player requires multiple client certificates or trust chains, they must ***all*** be included in the *.bsca*. So .*bsca* packages must be updated frequently if different sets of servers have differing certificate expiration dates.
- The player must be temporarily offline from the CMS to install the .*bsca* and it generally requires manual intervention/attention from someone with direct network access to the player.
- Factory reset clears installed .*bsca* certificates. This can be an issue for CMS systems that deliver configuration files that issue a factory reset and then (re)apply settings, as the (re)applied settings would not include the .bsca installation, potentially resulting in the player not being able to contact the CMS, mandating on-site or near-site (on-network) access to the player.

# Other

- Only one .*bsca* file can be added to the player. So, if you send a different .*bsca*, it will replace the prior one.
- You can't delete any preinstalled certs already in the keystore. You can only delete your .*bsca* file and the certificates that are inside it by installing a new file.
- See also [Fix Expired CA Certificates](docId\:OTEpkNUKiRRuin8YXJv6t).
- Players must sync with a time server to ensure that the player date and time is accurate.
- Customers upgrading from Cisco ISE 3.1 to ISE 3.4 or later may experience 802.1x EAP-TLS authentication failures even when using the same certificate files and player configuration that previously worked. ISE 3.4 enforces strict RFC certificate chain ordering. The player certificate file must present the Root CA (RCA) before the Intermediate CA (ICA). ISE 3.1 accepted the reversed order; ISE 3.4 does not. When the chain is reversed, the player sends an ISE error: 12520 - "EAP-TLS failed SSL/TLS handshake because the client rejected the ISE local-certificate"; OpenSSL reports "unknown CA" (TLS alert 48) To resolve this, open the player certificate file and reorder the chain so the Root CA appears first, followed by the Intermediate CA. Redeploy the updated file to the player and retry authentication.