3 Security

This chapter discusses security with the Oracle Java ME Embedded environment. Note that with version 8 of the OJMEE, the security system was changed considerably, and now uses Java SE-style fine-grain permissions. In addition, a security policy must be chosen and JAR files, if applicable, must be digitally signed in order for peripherals to be accessed.

3.1 Permissions for Accessing Peripherals

Applications that require access to peripherals or resources must request appropriate permissions in the JAD file. For more information on using the Device I/O APIs, please see the Device I/O API Proposal for Java ME 8 specification and the associated Javadocs at the following site:

http://docs.oracle.com/javame/embedded/embedded.html

Table 3-1 gives a list of all permissions that can be requested in the Oracle Java ME Embedded environment, as well as a description of when they are applicable.

Table 3-1 Oracle Java ME Embedded Permissions

Permission	Description
`jdk.dio.adc.ADCPermission`	Use of analog-to-digital converter (ADC)
`jdk.dio.atcmd.ATPermission`	Use of AT communication line
`jdk.dio.counter.CounterPermission`	Use of the hardware counter
`jdk.dio.dac.DACPermission`	Use of digital-to-analog converter (DAC)
`jdk.dio.DeviceMgmtPermission`	Opening of any Device I/O peripheral.
`jdk.dio.generic.GenericPermission`	Use of the generic classes
`jdk.dio.gpio.GPIOPinPermission`	Use of a General Purpose I/O (GPIO) pin
`jdk.dio.gpio.GPIOPortPermission`	Use of a General Purpose I/O (GPIO) port
`jdk.dio.i2cbus.I2CPermission`	Use of the I2C bus on the board
`jdk.dio.mmio.MMIOPermission`	Use of the MMIO capabilities on the board
`jdk.dio.PeripheralMgmtPermission`	Use of any peripherals on the board
`jdk.dio.spibus.SPIPermission`	Use of the SPI bus on the board
`jdk.dio.uart.UARTPermission`	Use of the UART bus on the board
`jdk.dio.watchdog.WatchdogTimerPermission`	Use of the watchdog timer on the board
`javax.microedition.apdu.APDUPermission`	Use of an APDU device (e.g., card reader) on a board
`javax.microedition.cellular.CellularPermission`	Use of cellular telephone functionality on a board.
`javax.microedition.event.EventPermission`	Use of events
`javax.microedition.io.CommProtocolPermission`	Use of a communications protocol
`javax.microedition.io.Connector.cbs`	Use of a Cell Broadcast Service (CBS) Connector
`javax.microedition.io.Connector.file.read`	Use of a file read Connector
`javax.microedition.io.Connector.file.write`	Use of a file write Connector
`javax.microedition.io.Connector.rtsp`	Use of a real-time streaming protocol (RTSP) Connector
`javax.microedition.io.Connector.sms`	Use of an SMS Connector
`javax.microedition.io.DatagramProtocolPermission`	Use of the datagram protocol
`javax.microedition.io.DTLSProtocolPermission`	Use of the Datagram Transport Layer Security (DLTS) protocol
`javax.microedition.io.FileProtocolPermission`	Use of a file protocol
`javax.microedition.io.HttpProtocolPermission`	Use of the HTTP protocol
`javax.microedition.io.HttpsProtocolPermission`	Use of the HTTPS protocol
`javax.microedition.io.IMCProtocolPermission`	Use of the Inter-MIDlet communication protocol
`javax.microedition.io.MulticastProtocolPermission`	Use of a multicast protocol
`javax.microedition.io.PushRegistryPermission`	Use of a push registry
`javax.microedition.io.SocketProtocolPermission`	Use of a socket protocol
`javax.microedition.io.SSLProtocolPermission`	Use of the Secure Sockets Layer (SSL) protocol
`javax.microedition.location.LocationPermission`	Obtain the current location
`javax.microedition.media.control.RecordControl`	Use of a recording feature on the device
`javax.microedition.media.control.VideoControl.getSnapshot`	Use of a video snapshot feature on the device
`javax.microedition.midlet.ActionsDeniedPermission`	A permission to deny actions on a device
`javax.microedition.midlet.AutoStartPermission`	A permission to autostart an IMlet suite on a device
`javax.microedition.pim.ContactList.read`	Read a contact list
`javax.microedition.pim.ContactList.write`	Write to a contact list
`javax.microedition.pim.EventList.read`	Read from an event list (calendar)
`javax.microedition.pim.EventList.write`	Write to an event list (calendar)
`javax.microedition.pim.ToDoList.read`	Read a to-do list
`javax.microedition.power.PowerStatePermission`	Access the current power state of the device
`javax.microedition.swm.SWMPermission`	Access the software management features of the Java ME Embedded runtime
`javax.wireless.messaging.cbs.receive`	Receive a Cell Broadcast Service (CBS) message
`javax.wireless.messaging.sms.receive`	Receive an SMS message
`javax.wireless.messaging.sms.send`	Send an SMS message

3.2 Accessing Peripherals

Applications that require access to Device I/O APIs must request appropriate permissions in JAD files. For more information on using the Device I/O APIs, please see the Device I/O API 1.0 specification and the associated Javadocs at the following site:

http://docs.oracle.com/javame/embedded/embedded.html

3.2.1 Signing the Application with API Permissions

First, the JAD file must have the proper API permissions. Here is how to sign the application both in NetBeans and without an IDE.

In NetBeans, right-click the project name and choose Properties. Select Application Descriptor, then in the resulting pane, select API Permissions. Click the Add... button, and add the appropriate permissions, as shown in Figure 3-1. Click OK to close the project properties dialog.

Figure 3-1 Adding Permissions Using the NetBeans IDE

Description of "Figure 3-1 Adding Permissions Using the NetBeans IDE"
If you are not using an IDE, you can manually modify the application descriptor file to contain the following permissions.
```
MIDlet-Permission-1: com.oracle.dio.DeviceMgmtPermission "*:*" "open"
```

3.2.1.1 Method #1: Signing Application Using the NetBeans IDE

The NetBeans IDE enables developers both to sign the applications with a local certificate and upload the certificate on the device. See the appropriate Getting Started Guide for your embedded platform to learn how to use the NetBeans IDE to sign your application.

3.2.1.2 Method #2: Signing Application Using a Command Line

This method is more complex, but is the preferred route for applications that are widely distributed. Here are the instructions on how to setup a keystore with a local certificate that can be used to sign the applications.:

Generate a new self-signed certificate with the following command on the desktop, using the keytool that is shipped with the Oracle Java SE JDK.

keytool -genkey -v -alias mycert -keystore mykeystore.ks -storepass spass -keypass kpass -validity 360 -keyalg rsa -keysize 2048 -dname "CN=thehost"

This command generates a 2048-bit RSA key pair and a self-signed certificate, placing them in a new keystore with a keystore password of spass and a key password of kpass that is valid for 360 days. You can change both passwords as desired.
Copy the certs directory from the board over to the desktop using an sftp client or scp command, change into the certs directory, and perform the following command using the mekeytool.exe command (or alternatively java -jar MEKeyTool.jar... if your distribution contains only that) that ships with the Oracle Java ME SDK 8 distribution.

{mekeytool} -import -MEkeystore _main.ks -keystore mykeystore.ks -storepass spass -alias mycert -domain trusted

This command imports the information in mykeystore.ks that you just created to the _main.ks keystore. After this is completed, copy the certs directory back to the board by using an sftp client or scp command.

Use the following commands to sign your application before deploying it to the board:

jadtool -addcert -chainnum 1 -alias myalias -keystore mykeystore.ks -storepass spass -inputkad myjad.jad -outputjad myjad.jad

jadtool -addjarsig -chainnum 1 -jarfile myjar.jar -alias myalias -keystore mykeystore.ks -storepass spass -keypass kpass -inputjad myjad.jad -outputjad myjad.jad

3.2.1.3 Method #3: Using NullAuthenticationProvider

This method allows to bypass a certificate check and execute unsigned applications as if they were signed and given all requested permissions. This method should be used only for development and debugging. Final testing must be done using a real certificate as described in method #1.

To use NullAuthenticationProvider, set the following property in the jwc_properties.ini file on the board:

[internal]
authentication.provider = com.oracle.meep.security.NullAuthenticationProvider

Note that the Java runtime must not be running when editing the jwc_properties.ini file.