Sign the app

Starting with the Dolby Conference Phone 3.1 release, the Dolby Conference Phone requires the app to be digitally signed with a certificate before it can be loaded. This article describes how to sign the app. Topics include:

  • Obtain a code signing certificate from Dolby
  • Digitially sign the app using the tool and certificate provided by Dolby
  • Whitelist devices to skip code validation
  • Debug code signing errors
  • Types of certificates

Obtain a code signing certificate from Dolby

The first step is to generate a Certificate Signing Request (CSR) using the openSSL command line tool. Run this command in the IDE or on any Linux machine.

#openssl req -nodes -newkey rsa:2048 -keyout private.key -out request.csr

Enter the following data as prompted by the openssl command.

InputSample valueNote
CountryUSThe country name of the developer
State or Province NameCAThe state or province name of the developer
Locality NameSunnyvaleThe locality (City) name of the developer
Organization NameYour companyThe company name of the developer
Organizational Unit NameYour divisionThe organizational unit name of the developer
Common Name (*)com.dolby.test-appThe common name (CN) for the certificate.

It must be in reverse domain format and must be unique.

Note: The common name must match the name property in the .app.cfg file.

Email address (*)email@yourcompany.comThe email address of the developer.

The command generates two files, one called request.csr (the CSR file), the other one called private.key (the private key file). Keep the private.key file in a secure location.

Email the request.csr file to dcpsdksupport@dolby.com. Dolby will review the request and, once approved, issue a certificate file called signing.cert which is emailed to the requestor. Use this certificate to sign the app.

Sign the app

Run the following command to sign the app. Use the private key file private.key that was generated from previous step as well as the code signing certificate received from Dolby.

Note: csaf-signtool.py can be found in the Dolby Conference Phone IDE /usr/local/bin folder.

#csaf-signtool.py update --directory app/ --private-key private.key --certificate-file signing.cert

The csaf-signtool.py script will iterate through the files under the app directory to generate checksums for each file. The app directory is the root directory of the app and where the .app.cfg file resides. The file checksum information is added to the .app.cfg file.

Note: Whenever any of the app files change, you as the developer must run the same command to update the checksums and the signature. You can whitelist devices to get around this requirement.

The following example shows an updated .app.cfg file; the code signing is complete.

{
    "certificate": "-----BEGIN CERTIFICATE-----
MIIGhjCCBG6gAwIBAgIJAOG8aIjXMAlPMA0GCSqGSIb3DQEBBQUAMIGIMQswCQYD
VQQGEwJVUzELMAkGA1UECBMCQ0ExEjAQBgNVBAcTCVN1bm55dmFsZTETMBEGA1UE
ChMKRG9sYnkgTGFiczEOMAwGA1UECxMFQ29tbXMxFjAUBgNVBAMTDTEwLjExMi4y
MDMuMzMxGzAZBgkqhkiG9w0BCQEWDGtkQGRvbGJ5LmNvbTAeFw0xNjExMDIxODM0
NThaFw0xNzExMDIxODM0NThaMIGIMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0Ex
EjAQBgNVBAcTCVN1bm55dmFsZTETMBEGA1UEChMKRG9sYnkgTGFiczEOMAwGA1UE
CxMFQ29tbXMxFjAUBgNVBAMTDTEwLjExMi4yMDMuMzMxGzAZBgkqhkiG9w0BCQEW
DGtkQGRvbGJ5LmNvbTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBALWZ
Ia59QQw/CV4y35o3797fZgSs8Jd1u2glbzYim3pzpf4MQTkNu1mWNRr4vlDTVdCp
89laaQHNk8SCjr14OMHyGm2sOywkLqqiiFA/jwSv/lb3SIhfGONqFTs7Y09kzPr7
QzfuoJgAX2S6KpXy0a4W30Dm5qZQPNJr1HRB5y0SmlaaaCq6odHIByHtWUSxjVzd
qyL0A4wxc5CCB5a6Y1810akOGpn9SYvHCrc3+686sA6mvDrDblMAdCHRa0uVxljB
----END CERTIFICATE-----\n",
    "checksums": {
        "Servermain.qml": "999ff81e977d15a652d56958ea56aa88a5b7aab8d18542524105dc74b370234f",
        "dvrsapp.qml": "bbdc83e2abca6fff9d50ce97fe92c59109482a8cd7367e0104e562eac18c46ec",
        "qml/ConfConnectingScreen.qml": "e0349ed91367c840381e1eeaaa9462c760540623cd5e4b6b0472d1e0aad8be75",
        "qml/ConferenceScreen.qml": "7ddf6a1fec907710c1242f8053bc91efeef386b8434076dbcec9432388288dea",
        "qml/DirectoryDataModel.qml": "9aea564cc1e24cf9c5bda2b48502db2bed3d0bfa8bd4ae87bd4efbfb0d442cb2",
        "qml/DirectoryTab.qml": "e955f2d186c37e7f389cd692acee1d26d4c008b7e214f1854ac897ea7c2c0e44",
        "qml/GlobalVariables.js": "55c35d6c6b85efb112c2dbccaf5c91af06c8bfcb0910250cedd116a767803381",
        "qml/InConferenceScreen.qml": "2c65f829452617504d04a3e454798441b5eeb8ed80ec70c14bf7a1da3ee342f7",
        "qml/InConferenceView.qml": "f7eef3d64e1db65a33f90b4e63f6e311b734c94c8cf511bff65c440092ad2f6b",
        "qml/JoinConferenceTab.qml": "7c0b8f4d5df2f839f75697137bb2b69b11dcd6e27f7ec0e452fa138dd258bd98",
        "qml/RosterView.qml": "5e259dd845ecb7cfec9200ba012b58386051ea2f84ac1a5ffbbba260c0dc5452",
        "qml/photos/user1.PNG": "e1746b4d41aef0884ea240fea674e32d363f1fc3ed5c95a8cb45ce0d34b4ebe0",
        "qml/photos/user2.PNG": "252857c548e778c469e0a193ac4f18dd816d734774dd569ba81e2a0b6c317147",
        "qml/photos/user3.PNG": "8fd84ccc057612414e8f845c2268969604fe6626c147ed2312b6d690780314a0",
        "qml/photos/user4.PNG": "730c248dfba0f755d8eb4e8905b0bce06b172db59823e63727b610e91dc3e65e",
        "qml/photos/user5.PNG": "ad6e8c4d9d9ceee0c1e4231b54949afb5446c1ad64a0da9baee9ccd934a3c413",
        "qml/photos/user6.PNG": "59ce3340cc2ee780e8c01e1907fbbd4476785876efcd380db1b81b3c36424cc2",
        "qml/photos/user7.PNG": "098d3b98a57f6983f193dd890e9691807b2af5fd8a060af5b878c3c7bc5015d9",
        "qml/photos/user8.PNG": "ed9c858371f6d6b7e59cbd2936026a79cb663b74b0bde8caf629506aafdb99f1",
        "qml/photos/user9.PNG": "a0c619436887dad7621d7ff4d2cd65634ec0e8d4a6478bd296cad2985517d772",
        "qml/photos/user10.PNG": "7653518125e7d6195c55f27b0c6f730d51ab4e8912092a343f7dc7a17ac5e6dc",
        "qml/photos/user11.PNG": "7bc6afbca81ea0c057f24fdb225db0ca954d29d281118535d132e144f6799cb4",
        "qml/photos/user12.PNG": "4f866207d89e5ed1de3014fd970b6511fa86d443c160bf97f20de492931d6805",
        "qml/photos/user13.PNG": "fe8cad5734e101b6cfbea7b5e76a7af0c2aea09eabcae452e54721e6a020cc1d",
        "qml/photos/user14.PNG": "fd1a5eb9e6b9ea6fe25cac6bf719a6e73cc75a7b74562209f01329dccb4234ae",
        "qml/qmldir": "52f9fa34af09a29e4caf0cb02ce55c0614d8bb5b290c225fbdd95bba9339174a",
        "qmldir": "5f35b4ec531c3e7b95fc9d2608d5a192273ef50c250f4d72fce62ab5acb29b14"
    },
    "contact": "dcpsdksupport@dolby.com",
    "developer": "Dolby",
    "name": "com.dolby.test-app",
    "version": "0.0.1"
}

The csaf-signtool.py also generates a signature file (.app.cfg.sig) for the .app.cfg. The signature file must be placed under the same directory on the app deployment server where the .app.cfg file resides.

The following example is a .app.cfg.sig file that contains a Base64 encoded digital signature for the .app.cfg file.

CutjYpO7cTgtGDv4znHkPjo8u9HMU86pSWoche6kYj2xsqVp8elsRpSJNmQ650+U
NZWiNtSLYNe2n2CEASCzXGFSCAhxZg9T7ky8ApzBmcYo/SlmP1zUDqARRVKatUn8
L8Ra/lr/laCXQakK0PV3Qw/0NESf0SJCntc1XmhFVOjdD1niq727ui3O/azVhPjE
1amodAgaluNGxizZKHRF/Il6wLAvp019x/zm53pio8otGoqJAlzHmxH5i6TYPYcM
Yk1n2WZRqIrDBAM3jir92Z6dvdEGbu8EvPIBjzlIvLTMcaONxMYxWXJvAlIeLs4C
fnFgHtCWZjVR3pVjx/+S13lzA5vHKglaeoz/EkdQls11VVHO+Asyi69EocKKXUHi
2FMtKe2SLa/NBKsGQX+NJ4Z/cf/VOW/beoNJQYbFDqgWL+4XwnlqE3Px7XjTja59
C7aV7TMvHHmIuJ3H5wL7zjInNCl71LR0UhSoYql9tWacnVJtaf3sK0OXz90OLCtI
hr4QyJcvZAUaQvX5gayuKxWt+HjNYMr+wPHfdke9NsYuY48iO6RfHzr7XgyEFeOL
N/UjgJjB2dJuf1GhByBPjvIqVOObDuBWONl0uhFwN9sH0kSljr/N+faa8/R0+ZU
w0VT0Es0ytwUyGjiQDtOvi9igRQEECwsN4cms0G0O7A=

Whitelist devices

During app development, you can whitelist the phones that are used for development purposes, so that you don't have to run the code signing process every time you make a change.

To whitelist one or more phones, add the following section to the .app.cfg file.

"whitelistSerialNumbers": [
      "D123456", "G563322"
  ]

D123456 and G563322 in the example above are Dolby Conference Phone serial numbers. You can find the device serial number on the bottom of the Dolby Conference Phone.

Note: If you make changes to the device whitelist, you will need to sign the app again.

Note: Validate the .app.cfg against JSON syntax after you made this change.

Debugging

The app loading status can be viewed on the Dolby Conference Phone embedded UI by tapping Settings > ... > About > Status > Conference app. The status message could contain one of the following error messages indicating an error related to app signing.

  • Invalid or missing certificate : Missing code signing certificate in the .app.cfg file, or the included certificate is not signed by Dolby.
  • Invalid or missing signature : Missing .app.cfg.sig file or the file contains an invalid signature.
  • Invalid or missing checksum : Missing or invalid code checksum in the .app.cfg file for one or more entries under the checkums element.

Type of certificates

There are two types of certificates; Dolby decides which type will be issued based on the description in your request email:

  • Production (valid for 10 years)
  • Development (valid for 6 months)

Expired or revoked certificates

Dolby Conference Phone will no longer be able to load apps that have been signed with expired or revoked certificate. You must distribute a new version of your app that is signed with a new certificate. If you suspect that your private key have been compromised, and would like to request revocation of the certificate, send an email to dcpsdksupport@dolby.com.