General iOS Server Configurations

This section includes the details on how to generate the Certificate Authority (CA), Registration Authority (RA) and SSL certificate. You can configure the steps using the script or you can configure it manually if you are updating your production environment. 

Configuring iOS server-side configurations using the script

This script automatically configures the iOS server-side configurations. This method is recommended because manually configuring the server-side configurations include many steps and if you miss out on a step you will run into errors.

Follow the steps given below:

1. Navigate inside the <IOTS_HOME>/ios-configurator directory and run the ios.sh script. 
   

   cd ios-configurator
   sh ios.sh

2. Enter the requested information when prompted. Be sure to provide the same information when configuring the iOS platform configurations.

   Field	Usage/Purpose
   Country	The name of your country. Enter the two digit code for your country.
   State	The state your organization is at.
   Location	The city your organization is located at.
   Organization	The name of your organization. For this scenario, we entered MobX.
   Organization Unit	Defined the Team ID as the organization unit.
   Email	The email is used to identify the existing users. For this scenario, we entered chris@mobx.com as the email.
   Commonname	Fully qualified domain name of your server.

   This part of the script creates a key pair, generates a signature, and signs the key using the signature.

Configuring iOS server-side configurations manually

Follow the instructions below to configure the iOS server-side configurations:

1. Create a new file named openssl.cnf in a preferred location.

2. Include the following configurations to the openssl.cnf file, to generate version 3 certificates as shown below:

   [ v3_req ] 
   # Extensions to add to a certificate request 
   basicConstraints=CA:TRUE 
   keyUsage = digitalSignature, keyEncipherment 
   
   [ v3_ca ] 
   # Extensions for a typical CA 
   # PKIX recommendation. 
   subjectKeyIdentifier=hash 
   authorityKeyIdentifier=keyid:always,issuer 
   # 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 = digitalSignature, keyCertSign, cRLSign

   Why is this step required?

   The CA, RA, and SSL certificates will be generated using the openSSL toolkit as explained in step 4, step 5 and step 6 respectively. Therefore, the openssl.cnf file must be configured as explained above.

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-THE-NEWLY-CREATED-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-THE-NEWLY-CREATED-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:

   If you have already obtained an SSL certificate for your domain, you can skip this step and use that SSL certificate in step 7.

   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., 192.168.1.157) 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. 

      If you are using intermediate certifications, make sure to create a single certificate file that includes all these certificates by archiving them using the cat <CERTIFCATE 1> <CERTIFICATE 2> ... >> <CERTIFICATE CHAIN> command. Use the generated certificate chain for the proceeding step.

      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. 

   Why is this step required?

   A PKCS12 file is used to store many cryptography objects as a single file. The certificates and their private keys that were generated using the above commands are stored in a PKCS12 file so that it can be imported to the respective KeyStores as shown in step 9.

7. Copy the three P12 extension files to the <IoT_HOME>/repository/resources/security directory.

   Why is this step required?

   The <IoT_HOME>/repository/resources/security directory is where the WSO2 IoT KeyStores are stored.
   Example for KeyStores: wso2carbon.jks, client-truststore.jks and wso2certs.jks.

8. Import the generated P12 extension files as follows:
   

   1. Import the generated <KEYSTORE>.p12 file into the wso2carbon.jks and client-truststore.jks in the <IoT_HOME>/repository/resources/security directory.
      keytool -importkeystore -srckeystore <KEYSTORE>.p12 -srcstoretype PKCS12 -destkeystore <wso2carbon.jks/client-truststore.jks>

      • When prompted, enter the keystore password and keystore key password as wso2carbon.
      • When prompted to replace an existing entry that has the same name as wso2carbon, enter yes.
        Example: Existing entry alias wso2carbon exists, overwrite? [no]:  yes

      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>/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 the keystore key password as cacert.

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


      Troubleshooting

      Why does the following error occur: " keytool error: java.io.IOException: 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, WSO2 IoT will automatically create a new wso2certs.jks file with the imported file.

9. The default IoT keystore details are defined under the <CertificateKeystore> XML element in the certificate-config.xml file, which is in the <IoTS_HOME>/conf directory. Therefore, if any of the following details are changed, it needs to be reflected in < CertificateKeystore>:

   • Certificate Keystore file location
   • Certificate Keystore type
   • Certificate Keystore password
   • Certificate authority certificate alias 
   • Certificate authority private key password
   • Registration authority certificate alias

   • Registration authority private key password 

   Example:

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <CertificateConfigurations>
       <CertificateKeystore>
           <!-- Certificate Keystore file location-->
           <CertificateKeystoreLocation>${carbon.home}/repository/resources/security/wso2certs.jks</CertificateKeystoreLocation>
           <!-- Certificate Keystore type (JKS/PKCS12 etc.)-->
           <CertificateKeystoreType>JKS</CertificateKeystoreType>
           <!-- Certificate Keystore password-->
           <CertificateKeystorePassword>wso2carbon</CertificateKeystorePassword>
           <!-- Certificate authority certificate alias -->
           <CACertAlias>cacert</CACertAlias>
           <!-- Certificate authority private key password -->
           <CAPrivateKeyPassword>cacert</CAPrivateKeyPassword>
           <!-- Registration authority certificate alias -->
           <RACertAlias>racert</RACertAlias>
           <!-- Registration authority private key password -->
           <RAPrivateKeyPassword>racert</RAPrivateKeyPassword>
       </CertificateKeystore>
       <!-- Certificate Mgt DB schema -->
       <ManagementRepository>
           <DataSourceConfiguration>
               <JndiLookupDefinition>
                   <Name>jdbc/DM_DS</Name>
               </JndiLookupDefinition>
           </DataSourceConfiguration>
       </ManagementRepository>
       <!-- Default page size of GET certificates API -->
       <DefaultPageSize>10</DefaultPageSize>
   </CertificateConfigurations>

What's next?

Congratulations, you are done configuring the server setting of WSO2 IoT Server for iOS.

Next, Generate the Certificates from the Apple Developer Portal.