---
title: roKeyStore
slug: develop/rokeystore
docTags: 
createdAt: 2025-03-11T07:07:18.732Z
---

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. The JavaScript equivalent is [keystore](docId:6Alp0AIXrZlHV4cBkebvz).

While CA packages (added using the `AddCAPackage()` method) are persistent, individual certificates added using the `AddCACertificate()` and `AddClientCertificate()` methods must be applied on each boot.

## 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](docId\:GhSZNW9eS8TEMURQXq-DU) section below for more details.

:::hint{type="info"}
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

:::hint{type="danger"}
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](mailto\: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](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](https://brightsign.biz) .

```text
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](mailto\: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 BrightSignOS 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

```text
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" 
```