This documentation is for WSO2 IoT Server 3.2.0. View the documentation for the latest release.
Page Comparison - Generating a BKS File for Android (v.10 vs v.11) - IoT Server 3.2.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Navigate to the openssl.cnf file of the OpenSSL installation. 

  2. Make a copy of the  the openssl.cnf  file file, move it to another location, and configure the file to generate version 3 certificates as shown below:

    Code Block
    [ v3_req ] 
    # Extensions to add to a certificate request 
    keyUsage = Digital Signature, Key Encipherment 
    [ v3_ca ] 
    # Extensions for a typical CA 
    # PKIX recommendation. 
    # This is what PKIX recommends but some broken software chokes on critical 
    # extensions. 
    basicConstraints = critical,CA:true 
    # So we do this instead. 
    #basicConstraints = CA:true 
    # Key usage: this is typical for a CA certificate. However since it will 
    # prevent it being used as an test self-signed certificate it is best 
    # left out by default. 
    keyUsage = Digital Signature, Certificate Sign, CRL Sign
  3. In the location where you modified and saved the openssl.cnf file, run the following commands to generate a self-signed Certificate Authority (CA) certificate (version 3) and convert the certificate to the .pem format:


    1. openssl genrsa -out <CA PRIVATE KEY> 4096 
      For example: openssl genrsa -out ca_private.key 4096
    2. openssl req -new -key <CA PRIVATE KEY> -out <CA CSR> 
      For example: openssl req -new -key ca_private.key -out ca.csr
    3. openssl x509 -req -days <DAYS> -in <CA CSR> -signkey <CA PRIVATE KEY> -out <CA CRT> -extensions v3_ca -extfile <PATH-TO-MODIFIED-openssl.cnf-FILE> 
      For example: openssl x509 -req -days 365 -in ca.csr -signkey ca_private.key -out ca.crt -extensions v3_ca -extfile ./openssl.cnf
    4. openssl rsa -in <CA PRIVATE KEY> -text > <CA PRIVATE PEM> 
      For example:  openssl rsa -in ca_private.key -text > ca_private.pem
    5. openssl x509 -in <CA CRT> -out <CA CERT PEM> 
      For example: openssl x509 -in ca.crt -out ca_cert.pem
  4. In the same location, run the following commands to generate a Registration Authority (RA) certificate (version 3), sign it with the CA, and convert the certificate to the .pem format. 

    1. openssl genrsa -out <RA PRIVATE KEY> 4096 
      For example:  openssl genrsa -out ra_private.key 4096

    2. openssl req -new -key <RA PRIVATE KEY> -out <RA CSR> 
      For example: openssl req -new -key ra_private.key -out ra.csr
    3. openssl x509 -req -days <DAYS> -in <RA CSR> -CA <CA CRT> -CAkey <CA PRIVATE KEY> -set_serial <SERIAL NO> -out <RA CRT> -extensions v3_req -extfile <PATH-TO-MODIFIED- openssl.cnf-FILE > 
      For example: openssl x509 -req -days 365 -in ra.csr -CA ca.crt -CAkey ca_private.key -set_serial 02 -out ra.crt -extensions v3_req -extfile ./openssl.cnf
    4. openssl rsa -in <CA PRIVATE KEY> -text > <RA PRIVATE PEM> 
      For example: openssl rsa -in ra_private.key -text > ra_private.pem
    5. openssl x509 -in <RA CRT> -out <RA CERT PEM> 
      For example: openssl x509 -in ra.crt -out ra_cert.pem
  5. Generate the SSL certificate (version 3) based on your domain/IP address:


    You must add your IP address/domain as the Common Name. Otherwise, provisioning will fail. 

    1. Generate an RSA key.
      openssl genrsa -out <RSA_key>.key 4096 
      For example:
      openssl genrsa -out ia.key 4096
    2. Generate a CSR file.
      openssl req -new -key <RSA_key>.key -out <CSR>.csr 
      For example:
      openssl req -new -key ia.key -out ia.csr 
      Enter your server IP address/domain name (e.g., as the Common Name else provisioning will fail.
    3. Generate the SSL certificate.
      openssl x509 -req -days 730 -in <CSR>.csr -CA ca_cert.pem -CAkey ca_private.pem -set_serial <serial number> -out ia.crt 
      For example:  
      openssl x509 -req -days 730 -in ia.csr -CA ca_cert.pem -CAkey ca_private.pem -set_serial 044324343 -out ia.crt
  6. Export the SSL, CA, and RA files as PKCS12 files with an alias.

    1. Export the SSL file as a PKCS12 file with "wso2carbon" as the alias. 
      openssl pkcs12 -export -out <KEYSTORE>.p12 -inkey <RSA_key>.key -in ia.crt -CAfile ca_cert.pem -name "<alias>" 
      For example:
      openssl pkcs12 -export -out KEYSTORE.p12 -inkey ia.key -in ia.crt -CAfile ca_cert.pem -name "wso2carbon"

    2. Export the CA file as a PKCS12 file with an alias.
      openssl pkcs12 -export -out <CA>.p12 -inkey <CA private key>.pem -in <CA Cert>.pem -name "<alias>" 
      For example: 
      openssl pkcs12 -export -out ca.p12 -inkey ca_private.pem -in ca_cert.pem -name "cacert" 
      In the above example, cacert has been used as the CA alias. 
    3. Export the RA file as a PKCS12 file with an alias.
      openssl pkcs12 -export -out <RA>.p12 -inkey <RA private key>.pem -in <RA Cert>.pem -chain -CAfile <CA cert>.pem -name "<alias>" 
      For example: 
      openssl pkcs12 -export -out ra.p12 -inkey ra_private.pem -in ra_cert.pem -chain -CAfile ca_cert.pem -name "racert" 
      In the above example, racert has been used as the RA alias. 
  7. Copy the three P12 files to the <IoT<IOTS_HOME>/core/repository/resources/security directory.
  8. Import the generated P12 files as follows:
    1. Import the generated <KEYSTORE>.p12 file into the wso2carbon.jks and client-truststore.jks in the <IoT_HOME>/core/repository/resources/security directory.
      keytool -importkeystore -srckeystore <KEYSTORE>.p12 -srcstoretype PKCS12 -destkeystore <wso2carbon.jks/client-truststore.jks>


      When prompted, enter the key store password and key store key password as wso2carbon.

      For example: 
      keytool -importkeystore -srckeystore KEYSTORE.p12 -srcstoretype PKCS12 -destkeystore wso2carbon.jks 
      keytool -importkeystore -srckeystore KEYSTORE.p12 -srcstoretype PKCS12 -destkeystore client-truststore.jks

    2. Import the generated <CA>.p12 and <RA>.p12 files into the wso2certs.jks file, which is in the <IoT_HOME>/core/repository/resources/security directory.
      keytool -importkeystore -srckeystore <CA/RA>.p12 -srcstoretype PKCS12 -destkeystore wso2certs.jks 

      For example:
      keytool -importkeystore -srckeystore ca.p12 -srcstoretype PKCS12 -destkeystore wso2certs.jks 
      Enter the keystore password as wso2carbon and keystore key password as cacert.

      keytool -importkeystore -srckeystore ra.p12 -srcstoretype PKCS12 -destkeystore wso2certs.jks 
      Enter the keystore password as  wso2carbon and keystore key password as racert.

      Why does the following error occur: " keytool error: Invalid keystore format"?

      If you enter the wrong private key password when importing the <CA>.p12 or <RA>.p12 files, the wso2certs.jks file will get corrupted and the above error message will appear.

      In such a situation, delete the wso2certs.jks file and execute the following command to import the generated <CA>.p12 and <RA>.p12 files into the wso2certs.jks file again.
      keytool -importkeystore -srckeystore <CA/RA>.p12 -srcstoretype PKCS12 -destkeystore wso2certs.jks

      When the above command is executed, IoTS will automatically create a new wso2certs.jks file with the imported file.


  1. Generate the BKS file:


    Ensure that you have Make sure to generate the BKS file into the same folder that has the bcprov-jdk16-1.46.jar file in the same folder where you will be generating the BKS file before you run this command.before running the command given below. Else, you get the error given below:

    Code Block
    keytool error: java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider
    java.lang.ClassNotFoundException: org.bouncycastle.jce.provider.BouncyCastleProvider
    	at java.lang.ClassLoader.loadClass(
    	at java.lang.ClassLoader.loadClass(
    Localtab Group
    titleUsed the change-ip script for step 1.
    Code Block
    keytool -noprompt -import -v -trustcacerts -alias wso2carbon -file c.crt -keystore truststore.bks -storetype BKS -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk16-1.46.jar -storepass 'wso2carbon'
    titleHaven't used the change-ip script for step 1.
    Code Block
    keytool -noprompt -import -v -trustcacerts -alias wso2carbon -file ca_cert.pem -keystore truststore.bks -storetype BKS -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk16-1.46.jar -storepass 'wso2carbon'

    If you are using an SSL certificate by a trusted authority such as GoDaddy, the cert.crt defined in the command should be the interim certificate.  


    Code Block
    keytool -noprompt -import -v -trustcacerts -alias godaddy -file cert.crt -keystore truststore.bks -storetype BKS -providerclass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk16-1.46.jar -storepass 'wso2carbon'
  2. Optionally, view the list of certificates in the BKS form using the following command:

    Code Block
    keytool -list -v -keystore "truststore.bks" -provider org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath "bcprov-jdk16-1.46.jar" -storetype BKS -storepass "wso2carbon"
  3. Copy the generated truststore.bks file to the <ANDROID_AGENT>/client/iDPProxy/src/main/res/raw directory and replace the original file. 
  4. Navigate to the <ANDROID_AGENT>/client/client/src/main/java/org/wso2/iot/agent/utils/ file, and configure the following:
    • Provide the HTTPS_HOST_IP as the value for the API_SERVER_PORT parameter.
      Example: 9443.
    • Change the SERVER_PROTOCOL to https://.
  5. Configure the following files to get SSL to work on the Android agent:


    Configure the build release you want to compile to get the customized agent. For example, you can build the release, debug, staging or standalone build releases to meet your requirement.

    1. Configure the SERVER_PROTOCOL property to https in the client/iDPProxy/build.gradle file.

      Code Block
      buildConfigField "String", "SERVER_PROTOCOL", "\"https://\""
    2. Configure the DEFAULT_HOST property with the server URL in the client/client/build.gradle file.

      Code Block
      buildConfigField "String", "DEFAULT_HOST", "\"\""

      After this configuration, the Android agent skips the following server URL entering screen during enrollment. 

  6. Navigate to the <ANDROID_AGENT>/client/iDPProxy/src/main/java/org/wso2/iot/agent/proxy/utils/ file, and provide the BKS file password as the value for the TRUSTSTORE_PASSWORD parameter.