Roku SDK Documentation : ifHttpAgent

The ifHttpAgent methods modify the way that URLs are accessed.

Implemented By

• roAppManager
• roAudioPlayer
• roGridScreen
• roImageCanvas
• roListScreen
• roParagraphScreen
• roPosterScreen
• roSGNode
• roSlideShow
• roSpringboardScreen
• roTextScreen
• roTextureManager
• roTextureRequest
• roUrlTransfer
• roVideoPlayer
• roVideoScreen

Supported Methods

Description of Methods

AddHeader(name as String, value as String) as Boolean

Add the specified HTTP header to the list of headers that will be sent in the HTTP request.

Certain well known headers such as User-Agent, Content-Length, etc. will automatically be sent.

The application may override these well known values if needed (e.g. some servers may require a specific user agent string).

If "x-roku-reserved-dev-id" is passed as a name, the value parameter is ignored and in its place, the devid of the currently running channel is used as the value.

This allows the developer's server to know which client app is talking to it. Any other headers whose name begins with "x-roku-reserved-" are reserved and may not be set.

SetHeaders(nameValueMap as Object) as Boolean

nameValueMap should be an roAssociativeArray.  Each name/value in the AA is added as an HTTP header.

Header limitations specified in AddHeader() still apply.

InitClientCertificates() as Boolean

Initialize the object to send the Roku client certificate.

SetCertificatesFile(path as String) as Boolean

Set the certificates file used for SSL to the .pem file specified.

The .pem file should include the CA (certificate authority) certificate that signed the certificate installed on your web server.

Note: The developer can download the CA certificate here. 

This enables authentication of your server.

Instances of roUrlTransfer and ifHttpAgent components should call this function before performing https requests.

The appropriate certificates file should be placed at the location specified in the SetCertificatesFile() function call.

SetCertificatesDepth(depth as Integer) as Void

Set the maximum depth of the certificate chain that will be accepted.

EnableCookies() as Void

Causes any Set-Cookie headers returned from the request to be interpreted and the resulting cookies to be added to the cookie cache.

GetCookies(domain as String, path as String) as Object

Returns any cookies from the cookie cache that match the specified domain and path. 

If domain is an empty string, all domains are matched. 

Any expired cookies are not returned. 

The returned object is an roArray of roAssociativeArrays.  Each AA contains the keys:

AddCookies(cookies as Object) as Boolean

cookies should be an roArray of roAssociativeArrays. 

Each AA should be in the same format as the AAs returned by GetCookie(). 

The specified cookies are added to the cookie cache.

ClearCookies() as Void

Removes all cookies from the cookie cache.

Server Side Configuration of SSL Mutual Authentication on Apache

1. Create a Self-Signed CA (Certificate Authority) root Certificate

   1. Create the CA private key (remember the password chosen):

      sudo openssl genrsa -out /opt/openssl/testCA/CA/testCA.KEY

   2. Create CA Certificate Request:

      sudo openssl req -new -key /opt/openssl/testCA/CA/testCA.KEY -out /opt/openssl/testCA/CA/testCA.CSR

   3. Self-sign the CA certificate:

      sudo openssl x509 -req -days 3650 -in /opt/openssl/testCA/CA/testCA.CSR -out /opt/openssl/testCA/CA/testCA.CRT \

      /opt/openssl/testCA/CA/testCA.KEY

2. OpenSSL Server Cert
   1. Create the Web Server's key (remember the password chosen):
      sudo openssl genrsa -des3 -out /opt/openssl/testCA/server/keys/testWEB.KEY 
   2. Create the Web Server's Cert Req:
      sudo openssl req -new -key /opt/openssl/testCA/server/keys/testWEB.KEY -out \ /opt/openssl/testCA/server/requests/testWEB.CSR
   3. Sign the Web Server's Cert Req with the CA Cert:
      sudo openssl ca -in /opt/openssl/testCA/server/requests/testWEB.CSR -cert /opt/openssl/testCA/CA/testCA.CRT -keyfile \ /opt/openssl/testCA/CA/testCA.KEY -out /opt/openssl/testCA/server/certificates/testWEB.CRT
3. Install Cert in Apache
   1. sudo mkdir /etc/httpd/certs
   2. sudo cp /opt/openssl/testCA/server/certificates/testWEB.CRT /etc/httpd/certs
   3. sudo cp /opt/openssl/testCA/server/keys/testWEB.KEY /etc/httpd/certs
   4. sudo cp sudo cp /opt/openssl/testCA/CA/testCA.CRT /etc/httpd/certs
   5. If you don't want to enter the passwd for testWEB every time Apache starts, you can remove the passwd from the keyfile:
      sudo cp /etc/httpd/certs/testWEB.KEY /etc/httpd/certs/testWEB.KEY.orig
      sudo openssl rsa -in /etc/httpd/certs/testWEB.KEY.orig -out /etc/httpd/certs/testWEB.KEY
   6. Edit /etc/httpd/conf.d/ssl.conf
      # Configure your server cert:
      SSLCertificateFile /etc/httpd/certs/testWEB.CRT
      SSLCertificateKeyFile /etc/httpd/certs/testWEB.KEY
      # Configure client cert authentication:
      SSLCACertificateFile /etc/httpd/certs/cacert.pem # from roku sdk
      SSLVerifyClient require
      SSLVerifyDepth 1
   7. Edit /etc/httpd/conf/httpd.conf: 
      # In <Directory> </Directory> tags where your video resides:
      #
      # Checking the x-roku-reserved-dev-id header value assures that it is
      # your package trying to connect to this directory.
      # 
      # You can find the dev-id of your brightscript package by going to the 
      # developer page on your Roku box, and selecting "Utilities".
      # On the "Utilities" page, select "Choose File", enter the passwd for that pkg, and hit "Inspect"
      # Copy the value for the "Dev ID:" parameter and paste it here:
      SetEnvIf x-roku-reserved-dev-id 6bb22ba64125f6da56fa4b7d6f2199a970d06672 let_roku_in
      SSLRequireSSL
      Order Deny,Allow
      Deny from all
      Allow from env=let_roku_in
   8. Restart Apache:
      sudo service httpd restart
4. Place your video in your Apache directory configured in step 3.g) above.
5. Modify the simplevideoplayer application to access the secure video:
   1. Add the testCA.CRT (The Certificate Authority cert) file to the 
      simplevideoplayer/source directory.
   2. In the appMain.brs:displyVideo() function, change the URL and video meta-data 
      to match the video you put on your server in step 4).
   3. Right before the "video.SetContent(videoclip)" line, add the following calls:
      video.Addheader("x-roku-reserved-dev-id","")
      video.SetCertificatesFile("pkg:/source/testCA.CRT")
      video.InitClientCertificates()
6. Test the authentication with and without the code in 5.c) above. If any of the three authentication methods above are ommitted you should get access denied. Note that you cannot successfully access the video until you've built a package, uploaded it to the channel store, and are running that channel via a channel code. A side-loaded developer app does not properly negotiate client certs or send the enforced dev-id value for the x-roku-reserved-dev-id header.