Signing and publishing

When you're finished developing your app and want to distribute it to users, you'll want to publish it to the BlackBerry World storefront. The BlackBerry World storefront is where users discover, download, and review your app. Before you can publish your app, you must cryptographically sign it using a BlackBerry ID token.

The signing application included with the BlackBerry 10 Native SDK adds cryptographic hash values to your application .bar file during the signing process. The hash values help verify the authorship of your app to other users and the BlackBerry 10 OS.

You can also use the BlackBerry ID token to create a debug token, which is required to run unsigned apps on the device. For more information about debug tokens, see Set up your environment.

To support upgrades, an app should be signed with a BlackBerry ID token that was created from the BlackBerry ID that was used to sign the original app. For subsequent releases of your app, you should increment the version number before you upload your app to the BlackBerry World storefront.

For more information about uploading your apps, check out the BlackBerry World storefront documentation .

Configuring signing

When you set up your development environment, the Momentics IDE for BlackBerry automatically checks for a BlackBerry ID token and lets you create one and upload it if the IDE doesn't detect an existing token. When you build an app, the .bar file that is created is automatically signed using the signing token that you specified.

If the BlackBerry Deployment Setup Wizard doesn't run for you when you first install the IDE, in Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences. In the Preferences dialog box, click Blackberry > BlackBerry Deployment Setup Wizard.

Follow the steps in the wizard to create a BlackBerry ID token. If you already have a BlackBerry ID token, you can browse to where the .zip file was downloaded previously. To manually configure app signing, in Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences. In the Preferences dialog box, click Blackberry > Signing.

Your BlackBerry ID token is valid for one year. When it expires, you need to create a new one. If you forget the password from the BlackBerry ID token, BlackBerry can't retrieve or reset it for you - you'll need to create a new token.

Find your BlackBerry ID token

Read more

The default location of your BlackBerry ID token varies depending on your operating system. When you generate your BlackBerry ID token, you should save the token to the location that's specified below.

Operating System

Location

Windows XP

%HOMEPATH%\Local Settings\Application Data\Research In Motion

The default %HOMEPATH% is C:\Documents and Settings\<username>.

Windows Vista and Windows 7

%HOMEPATH%\AppData\Local\Research In Motion

The default %HOMEPATH% is C:\Users\<username>.

Mac OS

~/Library/Research In Motion

UNIX and Linux

~/.rim

Link a BlackBerry ID account to an older set of signing keys

Read more

If you have an older signing account that doesn't use a BlackBerry ID token, you can link your old signing keys (a barsigner.db or barsigner.csk file) to a BlackBerry ID account manually. If you run the deployment setup wizard and a barsigner.db or barsigner.csk file exists on your computer, the BlackBerry ID option isn't available in the Momentics IDE wizard, at which point you can use the command-line tools to link your BlackBerry ID account to your existing signing authority account.

By linking your BlackBerry ID account to your old code signing keys, you can continue to produce .bar files with the same Author ID, Package ID, and Package Name. Using the same values allows you to submit new releases of an existing app. When using the command-line tools, you have a few options:

  • Link your current barsigner.csk file to the bbidtoken.csk file, where both passwords are same:
    blackberry-signer -linkcsk –cskpass <Legacy CSK password or BBID Token CSK password>
  • Link your current barsigner.csk file to the bbidtoken.csk file, where bbidtoken.csk is in a location other than the default directory and both passwords are the same:
    blackberry-signer -linkcsk –bbidtoken <BBID Token CSK filename> –cskpass <Legacy CSK password or BBID Token CSK password>
  • Link your current barsigner.csk file to the bbidtoken.csk file, where both are in the default directory:
    blackberry-signer -linkcsk –oldcskpass <Legacy CSK password> 
    –bbidcskpass <BBID Token CSK password>

Configure additional settings for proxy servers

Read more

If your computer uses a proxy server to connect to the Internet, you must configure the Momentics IDE to use your proxy server.

  1. In Windows and Linux, on the Window menu, click Preferences. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand General and click Network Connections.
  3. On the Network Connections page, in the Active Provider drop-down list, click Manual.
  4. In the Proxy entries section, select the HTTP schema. Click Edit.
  5. In the Host field, specify the host address for your proxy server.
  6. In the Port field, specify the host port number for your proxy server, and click OK.
  7. Click OK.

Configure signing from the command line

Read more

Before you configure signing using the command line, you must create a BlackBerry ID token to be able to sign BlackBerry 10 applications. When you confirm your password, the keystore file you download will contain your signing token. When you get the BlackBerry ID token, store it in the default directory for your operating system, as described earlier.

To configure signing, run the following blackberry-keytool command to create a Developer Certificate for code signing. The password you specify in the -storepass parameter allows you to use the .p12 file to sign .bar files. You should protect the .p12 file and its password. The recommended practice is to use the same password for your Developer Certificate that you used for your BlackBerry ID token.

blackberry-keytool -genkeypair -storepass <storepass> -dname "cn=<company_name>" 

Here's the full set of parameters for blackberry-keytool.

Parameter

Description

genkeypair

Instructs the tool to generate a pair of mathematically related values used to encrypt and decrypt data. Data encrypted with one value must be decrypted by the other value. Anyone can verify an app encrypted with one value, which is kept private (signed using the private key), by decrypting it with the other value (the public key).

keystore

Specifies the location of the file that contains the public and private key pair.

storepass

Specifies the password that is used to control access to the key store.

dname

Specifies the name to associate with the certificate that the tool creates. The value for this parameter must match exactly:
  • the name you entered in the Company field on the web form to request permission to sign apps
  • the author element in your bar-descriptor.xml file

alias

Refers to an entry in the key store database. The value for this parameter must be the literal value author.

If you connect to the Internet through a proxy server, append the following additional options to the blackberry-keytool commands.

Option

Description

-proxyhost host

The network host that provides the proxy service. The host parameter can be an IP address or a fully-qualified domain name.

-proxyport port

The port number that the blackberry-signer and blackberry-debugtokenrequest use to communicate with the BlackBerry Signing Authority.

-proxyusername

user name

The user name to use when the proxy server requires authentication.

-proxypassword

password

The password to use when your proxy server requires authentication.

Signing your app

Each app has a corresponding version number. The version number for an app comprises a series of three numbers separated by decimals, followed by a build ID (for example 1.0.5.357).

Major.Minor.Revision.BuildID

If the app you're signing is an update for an existing app, ensure that you increment the version number before you sign it. You can change the major, minor, and revision components of the versionNumber element in the bar-descriptor.xml file.

After you increment the version number of your app, you can sign it using the following steps:

  1. In the IDE, click File > Export.
  2. Expand BlackBerry, select Release Build, and then click Next.
  3. On the Release Build page, select the project you want to export, and specify an export location for your app. If you don't specify a location, the app is exported to the project directory. Click Next.
  4. On the Digital Signature tab on the Packaging Settings page, select Enable digital signature and click Finish.

    The IDE signs and packages your app in the output .bar file.

If your app's bar-descriptor.xml file contains a <invoke-target id=""> property that any other signed app uses, signing fails. This problem often occurs if you use the default project name for your app. If you encounter this problem, change the <invoke-target id=""> property in the bar-descriptor.xml file to something unique to your app, or create a project using a new name.

Sign your app from the command line

Read more

You can also sign your apps by using the command line instead of using the Momentics IDE. If you didn't sign your application during the packaging process using the blackberry-nativepackager tool, you can sign it after the packaging process using the blackberry-signer tool.

To sign your app by using the blackberry-signer tool, you need to specify the keystore password that you created when you configured app signing in the -storepass parameter.

blackberry-signer -storepass KeystorePassword BAR_file.bar

The following table describes the complete list of parameters for the blackberry-signer tool.

Parameter

Description

csksetup

Instructs the tool to generate a pair of mathematically related values used to encrypt data exchanged during communication with the BlackBerry Signing Authority.

cskpass

This parameter specifies the password that is used to control access to the key pair created by using the csksetup parameter

register

This parameter instructs the tool to request that the BlackBerry Signing Authority associate a CSJ registration file with the public key that is created by using the csksetup parameter

csjpin

This parameter specifies the PIN for the CSJ registration file that is submitted during a registration request.

CSJ file

This parameter specifies the location of the Developer Certificate from the BlackBerry Signing Authority.

If you connect to the Internet through a proxy server, you must append the following additional options to the blackberry-signer and blackberry-debugtokenrequest commands.

Option

Description

-proxyhost &nbsp;host

The network host that provides the proxy service. The host parameter can be an IP address or a fully qualified domain name.

-proxyport&nbsp;port

The port number that the blackberry-signer and blackberry-debugtokenrequest use to communicate with the BlackBerry Signing Authority.

-proxyusername&nbsp;user name

The user name to use when the proxy server requires authentication.

-proxypassword&nbsp;password

The password to use when your proxy server requires authentication.

Example: blackberry-signer command line

blackberry-signer -proxyhost 192.168.1.1 -proxyport 80 -register 
                -csjpin PIN -storepass KeystorePassword AppSigningCSJFile DebugTokenCSJFile

Example: blackberry-debugtokenrequest command line

blackberry-debugtokenrequest -proxyhost 192.168.1.1 -proxyport 80 -storepass password -devicepin device-pin [options] debug-token-bar-file

Troubleshooting

If something goes wrong, you can revisit the Signing page in the Momentics IDE to change signing settings. To view the Signing page:

  1. Open the Preferences window.
    1. In Windows and Linux, on the Window menu, click Preferences.
    2. In Mac OS, on the Momentics menu, click Preferences.
  2. Expand BlackBerry, and then select Signing.
  3. Click BlackBerry Deployment Setup Wizard.
  4. Follow the steps in the wizard to configure your BlackBerry ID token.

The following section lists the errors that might occur during signing and provides potential solutions.

Description: During the signing process, the signing tool makes a copy of the input BAR file (.bar file). After the tool signs the copy of the BAR file successfully, the copy is renamed to the original input file name and the original file is deleted. This error indicates that one of these rename operations failed.

Possible Solution: Make sure that you have permissions to modify files in the folder where your BAR file is stored.

Code signing request failed because Application-Development-Mode in Manifest is present and is not set to false

Description: This message appears when you try to sign a BAR file that was packaged in Development mode.

Possible Solution Repackage the BAR file. If you use blackberry-nativepackager, or another command line tool, don't include the debug option in your command line.

Code signing request failed because the Package-Name in the Manifest is restricted from general use

Description: Your app has a name that is restricted.

Possible Solution: Change the name of your project, recompile, and repackage it.

Code signing request failed because the Invoke-Target-Key has been previously used in a different package

Description: This error occurs if another developer or another package already uses an Invoke-Target-Key that is specified in the .bar file being signed.

Possible Solution: Use a different Invoke-Target-Key.

Description: This message appears when you try to run the blackberry-signer tool with the register option, but you didn't include both the cskpass and csjpin options.

The blackberry-signer tool tries to encrypt communication between your computer and the BlackBerry Signing Authority. The tool stores the encryption keys in an encrypted file that's designed to be unlocked by using the password you provide in the cskpass option.

The CSJ Pin is a 6- to 10-digit number you selected when you requested permission to sign apps. The number is designed to verify that the CSJ registration file is used only by the person who requested it.

Possible Solution: Add the cskpass and csjpin options to your command line. Make sure you provide appropriate values for each option.

Code signing request failed because the Invoke-Target-Key in the Manifest is restricted from general use

Description: This error occurs if the Invoke-Target-Key specified in the .bar file being signed uses a restricted name.

Possible Solution: Use a different Invoke-Target-Key.

Description: You requested a signature from the BlackBerry Signing Authority, but didn't include the cskpass option. To contact the BlackBerry Signing Authority, the blackberry-signer tool must decrypt the barsigner.csk file using the password you provide using the cskpass option.

Possible Solution: Include the cskpass parameter and the password in your command line.

Developer certificate and private key not found in keystore or store password not supplied

Description: You attempted to sign an app using the blackberry-signer tool, but you didn't provide a value for the storepass option, or your Developer Certificate has no private key named "author".

Possible Solution: Verify that your command line includes the storepass option and specifies the correct password. Or, recreate your Developer Certificate. You can use the blackberry-keytool tool. Make sure that you provide the literal value "author" (not your name) for the alias option.

Description: The Developer Certificate that you provided to the blackberry-signer tool was issued by a Certificate Authority. However, the series of signatures (from a root authority to your certificate) that establish the authenticity of your certificate wasn't found in your keystore along with your Certificate.

Possible Solution: Add the certificate chain to the keystore.

Description: The blackberry-signer tool found an app signing key using the keyname parameter you specified on the command line. However, the key found is inappropriate for application signing.

Possible Solution: When you request a signature from the BlackBerry Signing Authority, make sure you specify RDK for the keyname parameter. Or, when you sign your BAR file using your Developer Certificate, make sure you specify author for the keyname parameter.

Description: The value you specified for the storepass option is incorrect. The blackberry-signer tool can't decrypt the keystore for your Developer Certificate.

Possible Solution: Provide the correct password for your keystore.

Description: You tried to use the blackberry-keytool tool to create a self-signed Developer Certificate. The tool doesn't have permission to write to the location you provided for the output_file.p12 parameter.

Possible Solution: Acquire read-write permissions for the folder to which you want to write the P12 file. Or, choose another location for your P12 file. Or, run blackberry-keytool with superuser permissions.

keytool error: java.lang.Exception: Key pair not generated, alias <author> already exists

Description: You tried to use the blackberry-keytool tool to create a self-signed Developer Certificate. The file name you provided for the output_file.p12 parameter already exists.

Possible Solution: Change the file name so that blackberry-keytool creates the output file using a different name or location. Or, delete your existing P12 file. Then run blackberry-keytool again.

Description: You specified a command line option, option_name, that takes a parameter. However, you didn't supply a value for the parameter.

Possible Solution: Provide a value for the parameter.

Description: This error appears when you try to use the blackberry-signer tool to sign or verify a .bar file, but no .bar file was specified on the command line.

This error can also appear when you try to use the blackberry-signer tool to register with the BlackBerry Signing Authority, but no CSJ file was specified on the command line.

Possible Solution: Specify the appropriate file.

Description: You can't sign your .bar file because you didn't specify a signing key.

The final parameter of the blackberry-signer tool specifies the key with which to sign your BAR file. Your BAR file must be signed twice: first by the BlackBerry Signing Authority, then by your Developer Certificate.

Possible Solution: Request a signature from the BlackBerry Signing Authority, by typing RDK at the end of your command line. Or, sign your .bar file using your Developer Certificate, by typing author at the end of your command line.

Description: The .bar file is corrupt.

Possible Solution: Repackage your project using the blackberry-nativepackager tool.

Description: You can't execute any of the following functions concurrently: setup, register, and verify. They are mutually exclusive operations.

Possible Solution: Perform these functions separately.

Description: The signing tool can't contact the BlackBerry Signing Authority.

A problem with the network connection prevents the blackberry-signer tool from contacting the BlackBerry Signing Authority. The signing tool can't sign your .bar file until it contacts BlackBerry Signing Authority.

Possible Solution: Check your computer's network connection.

Description: The blackberry-signer tool can't read the .bar file you specified on the command line. You may not have permission to access this file, or the file may be missing or corrupt.

Possible Solution: Verify that you have permission to access the file and that it exists at the location you provided on the command line. If the file exists and you have access to it, then try repackaging your project using the blackberry-nativepackager tool.

Publishing your app

After you sign your app, you can publish it by submitting it to BlackBerry World.

For more information about publishing your app, visit BlackBerry World .

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus