Page tree
Skip to end of metadata
Go to start of metadata

ON THIS PAGE


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 AddCACertificate() and AddClientCertificate() methods) are not; individual certificates must be registered with the certificate database after each reboot.

ifKeyStore

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.

Note

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

Important

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 support@brightsign.biz 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 https://brightsign.biz, you would specify a "nickname" of "brightsign.biz:443".

The following example uses an openssl terminal to generate a .p12 client certificate to use with https://brightsign.biz.

openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12 -name "brightsign.biz:443"

ifUserData

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.

ifMessagePort

SetPort(port As roMessagePort)

Posts messages to the attached message port.

Generating a CA Package 

Contact support@brightsign.biz 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. 

 


 

Example
k=createobject("rokeystore")
k.addcacertificate("ssd:/apache.crt")
aa = CreateObject("roAssociativeArray")
aa.AddReplace("certificate_file", "ssd:/client.p12")
aa.AddReplace("passphrase", "1q2w3e4r")
k.addclientcertificate(aa)


if k.AddCaPackage("ssd:/example.bsca") then print "CA Package added"
pkglist = k.GetCAPackagesInstalled()
print pkglist
if k.RemoveCAPackage("Example") then print "Removed CA Package" 

 

 

  • No labels