Appendix D:  Security Part 1

This appendix goes over some topics that should be considered for secure Kapsel apps.

HTTPS
Whitelist Connections
Password Policy
Feature Restriction
Using SAML with Kapsel
Additional Security Topics in Part 2

The following are some additional links on security.
SMP 3 – Security Concept and Features and the link to the recording 2014 Webinars
How to change SMP3 Keystore and Truststore Passwords
An Introduction to Content Security Policy
Android Security Tips
Protecting Data Using On-Disk Encryption
iOS Security

HTTPS

Hypertext Text Transfer Protocol Secure (HTTPS) can be used to communicate between the mobile app and the SMP 3.0 server and between the SMP 3.0 server and the OData endpoint rather than HTTP.  HTTPS provides a reasonable guarantee that one is communicating with precisely the web site that one intended to communicate with (as opposed to an imposter), as well as ensuring that the contents of communications between the user and site cannot be read or forged by any third party.

The video SSL Certificate Explained may be useful if you are not very familiar with SSL and HTTPS.

The SMP 3.0 server uses port 8080 by default for HTTP and port 8081 for HTTPS.  In addition, port 8082 is used for mutual authentication (clientAuth=”true”) and port 8083 is used for the management cockpit.  As of SP04, these ports have a specific name (see the smpConnectorName tag below) and the port is configurable in the Management Cockpit under Settings > Connectors.  For additional details on how the ports are configured see the file

C:\SAP\MobilePlatform3\Server\config_master\org.eclipse.gemini.web.tomcat\default-server.xml

<Connector acceptCount="100" connectionTimeout="20000" enableLookups="false" maxThreads="250" port="8080" protocol="HTTP/1.1"
redirectPort="8081" server="SAP" smpConnectorName="noSSL" />

<Connector SSLEnabled="true" ciphers="TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA" clientAuth="false"
keyAlias="smp_crt" maxThreads="200" port="8081" protocol="com.sap.mobile.platform.coyote.http11.SapHttp11Protocol" scheme="https"
secure="true" smpConnectorName="oneWaySSL" sslEnabledProtocols="TLSv1.2" sslProtocol="TLS" />

<Connector SSLEnabled="true" ciphers="TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA" clientAuth="true"
keyAlias="smp_crt" maxThreads="200" port="8082" protocol="com.sap.mobile.platform.coyote.http11.SapHttp11Protocol" scheme="https"
secure="true" smpConnectorName="mutualSSL" sslEnabledProtocols="TLSv1" sslProtocol="TLS" />

<Connector SSLEnabled="true" ciphers="TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA" clientAuth="false"
compressableMimeType="text/html,text/xml,application/javascript,text/json,text/plain,application/json" compression="on"
compressionMinSize="2048" keyAlias="smp_crt" maxThreads="200" port="8083" protocol="com.sap.mobile.platform.coyote.http11.SapHttp11Protocol"
scheme="https" secure="true" smpConnectorName="AdminSSL" smpServiceType="admin" sslEnabledProtocols="TLSv1" sslProtocol="TLS" />

<Connector SSLEnabled="true" ciphers="TLS_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_128_CBC_SHA" clientAuth="false" keyAlias="serverkey" maxThreads="200" port="443" protocol="com.sap.mobile.platform.coyote.http11.SapHttp11Protocol" scheme="https" secure="true" smpConnectorName="customSSLConnector" sslEnabledProtocols="TLSv1.2,TLSv1.1,TLSv1" sslProtocol="TLS"/>

Note that in SMP 3.0 SP07 of the server, a change was made to no longer support versions older than TLSv1.2 SSL by default.  SP08 SDK Hybrid Apps running on Android do not support HTTPS using TLS 1.2 with the Logon plugin to register.  To workaround this add TLSv1 and TLSv1.2 as shown above.  TLSv1.2 should be supported by the Logon plugin in SP09 of the SDK.  See HTTPS Connection Problem.

The error message on Android is

javax.net.ssl.SSLProtocolException: SSL handshake aborted: ssl=0x7a4ccbc8: Failure in SSL library, usually a protocol error

The above xml file shows a new entry added to support HTTPS on port 443 using a certificate with an alias of serverkey and a smpConnectorName of customSSLConnector.
Note that the SMP 3.0 server requires a restart after making changes to the default-server.xml file.
Also note that the alias of the certificate used by the SMP 3.0 server for connections to 8081, 8082 and 8083 (Management Cockpit) is smp_crt.

A new certificate can be created in the SMP 3.0 keystore (C:\SAP\MobilePlatform3\Server\configuration\smp_keystore.jks) using the Java KeyTool command as shown below.

keytool -genkeypair -alias serverkey -dname cn=YKFN00528072A.amer.global.corp.sap,c=CA -keystore smp_keystore.jks -storepass changeit -keyalg RSA -validity 360 -keysize 2048

Note that the storepass parameter takes the password entered for the SMP 3.0 keystore which is set during the installation of the SMP 3.0 server.
The common name must be the fully qualified domain name of the machine that the SMP 3.0 server is running on.  This must match the name entered into the browser to access the site.  For example the site must be accessed using https://YKFN00528072A.amer.global.corp.sap and not https://localhost or https://ip_number.
Note that SMP 3.0 server must be restarted after making changes to the smp_keystore.jks file.

It is possible to use self-signed certificates in a desktop browser.  The browser will however not be able to verify the certificate as it was not signed by a certificate authority that the browser trusts and will indicate this as shown below.

The self-signed certificate can be imported into the browser’s certificate authority’s store.
To do so, click on Details > Copy To File > Next > Base-64 encoded X.509 > C:\temp\serverkey.
Then click on Settings > type in cert in the Search settings > Manage certificates > Trusted Root Certification Authorities > Import > c:\temp\serverkey.cer.
At this point the self-signed certificate used by the SMP 3.0 server to identify itself and encrypt communication using SSL will now appear as a Trusted Root Certificate Authority as shown here. 

Once the certificate is installed into the Trusted Root Certification Authorities store and the page is next opened in Chrome (after all instances of Chrome have been shut down), there will no longer be a certificate error (Notice the https and lock icon in the address bar is green) as shown below.

Note that the default port number for HTTPS communication is 443 which is why 443 is not shown in the browser’s URL.

The same process can be used to install the certificate used by the Management Cockpit so that when opening the Management Cockpit the user is not presented with a warning screen.

A better solution is to replace the self-signed smp_crt certificate with a certificate that has been signed by your company’s certificate authority or one of the standard certificate authorities.

When a certificate is signed by a Certificate Authority (CA) that is known to the browser, it is not necessary to manually install the certificate.  The browser contains the CA in its trusted root certificate authorities and will trust certificates that have been signed by that CA.  Here we can see that the certificate used by the Netweaver Gateway demo system was signed by Starfield Secure Certification Authority.

It is possible to view the trusted certificate authorities available to a browser such as Chrome by choosing Settings > Show Advanced Settings > HTTPS/SSL > Manage Certificates

The SMP 3.0 server stores its certificates into the file named C:\SAP\MobilePlatform3\Server\configuration\smp_keystore.jks.  One tool which provides a graphical view of the contents of keystores is KeyStore Explorer.

In the image above, we can see that the previously created key with an alias of serverkey is a self-signed certificate as the issuer is the same as the subject.  Two other certificates of interest are smp_crt which is the default self-signed certificate used by the SMP 3.0 server and the sapgatewaycert used by the SAP Gateway demo OData source.  The sapgatewaycert was installed even though the certificate is signed by a certificate authority because the certificate authority Starfield Secure Certification Authority is not included in smp_keystore.jks.  Alternatively, we could have installed the Starfield Secure Certification Authority certificates into smp_keystore.jks.

Unlike a desktop browser such as Chrome, it is not possible to install a self-signed certificate into the device’s trusted credentials store to establish an HTTPS connection between the SMP 3.0 server and a mobile device or simulator in a Cordova app.  A certificate signed by a certificate authority is required.  It is possible to create your own certificate authority using Open SSL and use that certificate authority to sign the server certificate.  The AuthProxy sample demonstrates how to sign a client certificate using a certificate authority created using Open SSL.  Another approach is to use an SSL provider such as VeriSign and request them to sign the certificate.  The below steps will demonstrate how to use the SAP Test Server Certificate Authority to sign the server certificate.

SAP provides SAP Trust Center Services

where one can either purchase a SSL server certificate or can try a test server certificate which is valid for eight weeks.

• Download the SAP SSL Test Server CA Certificate from SAP Trust Center Service – Root Certificates.

  The file is named getCert.cer by default.  Rename it to SAPServerCA.cer.
  Import it into the smp_keystore.jks store.

  keytool -importcert -alias sapserverca -file SAPServerCA.cer -keystore smp_keystore.jks -storepass changeit
  

  Generate a certificate signing request (CSR).

  keytool -certreq -keyalg RSA -alias serverkey -file server.csr -keystore smp_keystore.jks -storepass changeit
  

  Open the webpage SSL Test Server Certificates and click on the Test it Now button.
  Open server.csr and copy the contents to the form, select other web server and click continue.
  Copy the resultant string and place it in a file named server.rsp.
  The below command will import the signed certificate into the keystore.

  keytool -importcert -alias serverkey -file server.rsp -keystore smp_keystore.jks -storepass changeit

  At this point the certificate serverkey is now signed by the SAP SSL Test Server Certificate Authority as shown below.
  

• A certificate in a keystore can also be viewed using the following command.

  keytool -list -v -keystore smp_keystore.jks -alias serverkey -storepass changeit

• The SMP 3.0 server needs to be restarted after making changes to the smp_keystore.jks.
• SAPServerCA.cer should be added to the device’s trust store so that the mobile device or emulator trusts the server certificate.

  For Android

  adb push SAPServerCA.cer /mnt/sdcard/
  adb shell
  cd /mnt/sdcard
  ls
  exit
  

  Install SAPServerCA.cer to the Android trusted credential store via

  Settings -> Personal -> Security -> Install from SD card (requires Android 4.0+)

  Note, that in the Android 4.4 emulator, the SAPServerCA.cer file did not appear in the list of available certificates to install.  A workaround is to rename the file to SAPServerCA.crt, copy it to C:\SAP\MobilePlatform3\Server\webapps\sapui5, and open the emulator’s browser to http://machine_name:8080/sapui5/SAPServerCA.crt.

  Note, on Android 4.4, a warning message is shown after a trusted credentials such as SAPServerCA is installed.  For further details see Network may be monitored.

  For iOS
  When using the iOS 7.0 emulator, the SAPServerCA.cer certificate can be installed by simply dragging and dropping it onto the emulator.

  When using an iOS device the SAPServerCA.cer certificate can be installed into the device’s trusted store by sending it via an e-mail or by opening the device browser to a webpage that contains a link to the certificate.  The certificate can be viewed and uninstalled under

  Settings -> General -> Profiles

Once a certificate that has not been self-signed is used, the secure toggle can be selected on the Registration screen.  This toggle can be set to true and the HTTPS port set via the Logon plugin’s context (see the index.html from the logon demo) as shown below.

// Optional initial connection context
    var context = {
        "serverHost": "YKFN00528072A.amer.global.corp.sap", //Place your SMP 3.0 server name here
        "https": "true",
        "serverPort": "443",
        ...
    }

In summary, when an HTTPS connection is established between a client and the server, the client verifies that the server certificate is signed by a certificate authority that the client trusts, that the certificate is not expired and the connection is coming from the host described in the server certificate.

For additional details on certificates see
www.sslshopper.com/ssl-faq.html
Common Keytool Commands
Changing Installed Certificates Used for HTTPS Listeners

Whitelist Connections

Cordova apps provide a setting in config.xml that lists what URLs can be accessed by the application.  By default the setting is set to *.  Change this to be the address of your SMP server to restrict network access to the URL specified.
On Android modify

LogonDemo\platforms\android\res\xml\config.xml

On iOS modify

LogonDemo\platforms\ios\LogonDemo\config.xml

<access origin="http://server1.mycompany.com" />

Note, the URL should be in lowercase.  Here is an example that demonstrates the error shown when trying to access a URL that has not been whitelisted. 

For additional details see Domain Whitelist Guide.

Note that the whitelist is case sensitive.  CB-5395

Password Policy

Before a Kapsel app can be opened that includes the Logon plugin, the unlock screen appears.  This application passcode can be used to provide additional security for the application.

The rules defining how often the password must be changed, the length of the password, if the password must include digits, upper and lower case letters etc. can be specified.

Note, if the app does not require an unlock screen, the button disable passcode can be pressed.

This requires that the option Default password allowed checkbox on the Client Password Policy screen be checked.

If the application does not register with an SMP 3.0 server, the passcode policy can be specified as shown below using the initPasscodeManager API call rather than init.

var passcodePolicy = {
    "expirationDays":"0",
    "hasDigits":"false",
    "hasLowerCaseLetters":"false",
    "hasSpecialLetters":"false",
    "hasUpperCaseLetters":"false",
    "defaultAllowed":"true",
    "lockTimeout":"0",
    "minLength":"6",
    "minUniqueChars":"0",
    "retryLimit":"0"
};

//Used if the application is not registering with the SMP 3.0 server.  New to SP03.
sap.Logon.initPasscodeManager(successCallback, errorCallback, appId, null, passcodePolicy, context);

Feature Restriction

In some cases, it may be a company policy to restrict certain types of functionality on a device.  Starting with SMP 3.0 Server SP05, the feature restriction capability provides this ability for a set of predefined Cordova plugins.  This list can be seen in the management cockpit under Application > Client Policy tab. 

In order to make use of this, the Settings plugin provides an API that can be used to see if a feature is available or not.

isFeatureEnabled(FeatureName, successCallback, errorCallback)

To try this out, start with the example shown in the Logon section named Accessing the Values Stored by the Logon Plugin.

• Add the Cordova contacts plugin and the Kapsel settings plugin.

  cordova plugin add org.apache.cordova.contacts
  cordova plugin add com.sap.mp.cordova.plugins.settings

  Each time the application starts a settings exchange will occur between the app and the SMP 3.0 server.  The information passed to the app includes the feature policy which is then accessible to the app.

• Add the following methods to index.html which will enable the selection of a contact from the list of contacts on the device.

  function pickContact() {
      //first check if the feature is enabled
      sap.Settings.isFeatureEnabled("navigator.contacts", isPickContactEnabledCallback, errorCallback);
  }
  
  function isPickContactEnabledCallback(enabled) {
      if (enabled) {
          navigator.contacts.pickContact(contactPickedCallback, errorCallback);
      }
      else {
          alert("The Contacts Plugin has been disabled by the feature restriction policy");    
      }
  }
  
  function contactPickedCallback(contact)  {
      alert("The following Conact was selected: " + JSON.stringify(contact));
  }
  
  function errorCallback(error) {
      alert(JSON.stringify(error));
  }
  
  

• Add a button to show the contacts picker.

  <button id="picker" onclick="pickContact()">Choose Contact</button>

• Copy the files to the platform directory by running

  cordova -d prepare

  Optionally modify the method SettingsExchangeDone in

  C:\Kapsel_Projects\LogonDemo\platforms\android\assets\www\plugins\com.sap.mp.cordova.plugins.settings\www\settings.js

  to display the info returned from the SMP server during the settings exchange.

  console.log("YYZ Settings are: " + JSON.stringify(JSON.parse(message)));
  

• Use the Android IDE or Xcode to deploy and run the project.  Click on Register and then press the Choose Contact button.
  

  Notice that the application has access to the device’s contacts.

• The next step will be to demonstrate how the functionality exposed through the Cordova contacts plugin can be disabled by an administrator.
  In the managment cockpit, select Applications > com.mycompany.logon > Client Policy > select the Contacts plugin in the Available Feature Policy table and click on Restrict.
• Exit and reopen the app. Notice that this time the contacts picker is not shown after the Choose Contact button is pressed.

Security Part 2

Back to Getting Started With Kapsel