This object allows you to register client certificates with the player. These certificates can be used by roHtmlWidget and roUrlTransfer objects when communicating with servers and roVideoPlayer objects when accessing streams. All object instances share the same certificate database.
While CA packages (added using the
AddCAPackage() method) are persistent, individual certificates (added using the
AddClientCertificate() methods) are not; individual certificates must be registered with the certificate database after each reboot.
GetFailureReason() As String
Returns additional useful information if an ifKeyStore method returns False.
AddCACertificate(certificate_file As String) As Boolean
Registers the specified CA certificate with the certificate database. Client certificates can be either self-signed or signed using a 3rd-party certificate issuer (Versign, DigiCert, etc.).
AddCAPackage(filename As String) As Boolean
Adds the specified CA package file to the certificate database. The package name resides in the file and does not need to be the same as the filename.
You will need to work with BrightSign to create a CA package to add to BrightSign players; see the Generating a CA Package section below for more details.
Attempting to modify a CA package file that has been added to the database will invalidate it. If a package is invalidated, it will need to be removed from the database (using the
RemoveCAPackage() method) and added again.
RemoveCAPackage(package_name As String) As Boolean
Removes the specified CA package from the certificate database. Use the
GetCAPackagesInstalled() method to retrieve a list of package names in the database.
GetCAPackagesInstalled() As roArray
Returns a list of names of CA packages contained in the certificate database.
AddClientCertificate(parameters As roAssociativeArray) As Boolean
Registers a .p12 client certificate with the certificate database. This method accepts an associative array with the following parameters:
certificate_file: The file name and path of the .p12 client certificate
passphrase: A passphrase for the .p12 client certificate
obfuscated_passphrase: An obfuscated passphrase for the .p12 client certificate
Provide the passphrase using either the "passphrase" or "obfuscated_passphrase" parameter (not both). We recommend using the "obfuscated_passphrase" in production environments, while the "passphrase" should be used for testing purposes only. Contact email@example.com to learn more about generating a key for obfuscation and storing it on the player.
BrightSign players use the "nickname" of a .p12 client certificate to match it with a website. The "nickname" consists of the
host:port of the web address you wish to match: For example, to use a client certificate for you would specify a "nickname" of
The following example uses an openssl terminal to generate a .p12 client certificate to use with.
SetUserData(user_data As Object)
Sets the user data that will be returned when events are raised.
GetUserData() As Object
Returns the user data that has previously been set via
SetUserData(). It will return Invalid if no data has been set.
SetPort(port As roMessagePort)
Posts messages to the attached message port.
Generating a CA Package
Contact firstname.lastname@example.org for help generating a CA package. You will need to provide a PEM file to BrightSign containing one or more root CAs that you would like the player to trust.
BrightSign will hash the CA file using SHA-256 and package it with an X.509 certificate containing the hash. The package will be signed by a CA that is trusted by the BrightSign OS for CA packaging only.
BrightSign packages the X.509 certificate with two strings:
- "friendly name": Specifies the package name, which will be returned by the
GetCAPackagesInstalled()method (and can be different from the filename of the CA package). You should specify the friendly name when you provide the CA file.
- "action": Currently, the only supported action is "add", which adds the contents of the CA package to the default BrightSign CAs.
BrightSign will send you the CA package as a .bsca file, which can then be added to BrightSign players using the
AddCAPackage() method. You can also inspect the package contents to determine if they are correct.