# Trusted MIDlet Suites using X.509 PKI

Signed MIDlet suites may become trusted by authenticating the signer of the MIDlet suite and binding it to a protection domain that will authorize the MIDlet suite to perform protected functions by granting permissions allowed in the protection domain. The mechanisms defined here allow signing and authentication of MIDlet suites based on X.509 Public Key Infrastructure so the device can verify the signer and trust the MIDlet suite.

If an implementation of this specification will recognize MIDlet suites signed using PKI as trusted MIDlet suites they MUST be signed and verified according to the formats and processes below.

The MIDlet suite is protected by signing the JAR. The signature and certificates are added to the application descriptor as attributes. The device uses them to verify the signature. The device completes the authentication using a root certificate bound to a protection domain on the device. The details of the processes and formats follow.

### References

MIDP 2.0 devices are expected to operate using standard Internet and wireless protocols and techniques for transport and security. The current mechanisms for securing Internet content is based on existing Internet standards for public key cryptography:

- [RFC2437] - PKCS #1 RSA Encryption Version 2.0
- [RFC2459] - Internet X.509 Public Key Infrastructure
- [RFC2560] - Online Certificate Status Protocol
- [WAPCERT] - WAP-211-WAPCert-20010522-a - WAP Certificate Profile Specification

### Definition of Terms

The terms Trusted MIDlet suite, Permission, and Protection Domain are defined by Security for MIDP Applications.

The following additional term is defined:

Term | Definition
--- | ---
Protection Domain Root Certificate | A certificate associated with a protection domain that the device implicitly trusts to verify and authorize downloaded MIDlet suites

### Signing a MIDlet Suite

The security model involves the MIDlet suite, a signer, and public key certificates. As with any public key system authentication is based on a set of root certificates which are used to verify other certificates. Zero or more root certificates will need to be on the device. Additionally, root certificates may be present in removable media such as SIM(WIM) card/USIM module. Implementations MUST support X.509 Certificates and corresponding algorithms. Devices MAY support additional signing mechanisms and certificate formats.

The signer of the MIDlet suite may be the developer or some entity that is responsible for distributing, supporting, and perhaps billing for its use. The signer will need to have a public key certificate that can be validated to one of the protection domain root certificates on the device. The public key is used to verify the signature on the MIDlet suite. The public key is provided as a RSA X.509 certificate included in the application descriptor.

Attributes defined within the manifest of the JAR are protected by the signature. Attributes defined within the application descriptor are not secured. When an attribute appears in the manifest it MUST NOT be overridden by a different value from the application descriptor. For trusted MIDlet suites the value in the application descriptor must be equal to the value of the corresponding attribute in the manifest. If not, the MIDlet suite MUST NOT be installed. The `MIDlet.getAppProperty` method must return the attribute value from the manifest if one is defined. If not, the value from the application descriptor (if any) is returned.

Note that the requirement that attributes values be equal differs from MIDP 1.0 and must be used for applications that are signed and verified by these procedures. For untrusted application descriptors, the MIDP 1.0 rule giving priority to application descriptor attributes over manifest attributes must be followed.

### Creating the Signing Certificate

1. The signer will need to be aware of the authorization policy for the device and contact the appropriate certificate authority. For example, the signer may need to send its distinguished name (DN) and public key (normally, packaged in a certificate request) to a certificate authority.
2. The CA creates a RSA X.509 (version 3) certificate and returns it to the signer.
3. If multiple CA's are used then all the signer certificates in the application descriptor MUST contain the same public key.

### Insert Certificates into the application descriptor

1. The certificate path includes the signer certificate and any necessary certificates but omitting the root certificate. The root certificate will be found on the device.
2. Each certificate in the path is encoded (using base64 but without line breaks) and inserted into the application descriptor as:

       MIDlet-Certificate-<n>-<m>: <base64 encoding of a certificate>

   <n>:= a number equal to 1 for first certification path in the descriptor or 1 greater than the previous number for additional certification paths. This defines the sequence in which the certificates are tested to see if the corresponding root certificate is on the device. See the Authenticating a MIDlet suite section below.
   <m>:= a number equal to 1 for the signer's certificate in a certification path or 1 greater than the previous number for any subsequent intermediate certificates.

### Creating the RSA SHA-1 signature of the JAR

1. The signature of the JAR is created with the signers private key according to the EMSA-PKCS1-v1_5 encoding method of PKCS #1 version 2.0 standard[RFC2437].
2. The signature is base64 encoded, formatted as a single MIDlet-Jar-RSA-SHA1 attribute without line breaks and inserted in the application descriptor.

       MIDlet-Jar-RSA-SHA1: <base64 encoding of Jar signature>

It should be noted that the signer of the MIDlet suite is responsible to its protection domain root certificate owner for protecting the protection domain stake holder's assets and capabilities and, as such, must exercise due-diligence in checking the MIDlet suite before signing it. In the case where there is a trusted relationship (possibly bound by legal agreements), a protection domain root certificate owner may delegate signing MIDlet suites to a third-party and in some circumstances, the author of the MIDlet.

### Authenticating a MIDlet Suite

When an MIDlet suite is downloaded, the device MUST check if authentication is required. If the attribute `MIDlet-Jar-RSA-SHA1` is present in the application descriptor then the JAR MUST be authenticated by verifying the signer certificates and JAR signature as below.

Application descriptors without the `MIDlet-Jar-RSA-SHA1` attribute are not authenticated but are installed and invoked as untrusted MIDlet suites.

### Verify Signer Certificate

The certification path consists of the signer certificate from the application descriptor and other certificates as needed up to but not including the root certificate.

1. Get the certification path for the signer certificate from the application descriptor attributes `MIDlet-Certificate-1-<m>` where <m> starts at 1 and is incremented by 1 until there is no attribute with the given name. The value of each attribute is a base64 encoded certificate that will need to be decoded and parsed.
2. Validate the certification path using the basic path validation processes described in RFC2459 using the protection domains as the authoritative source of protection domain root certificates. Bind the MIDlet suite to the protection domain that contains the protection domain root certificate that validates the first chain from signer to root and proceed with installation.
3. If attributes `MIDlet-Certificate-<n>-<m>` with `<n>` greater than 1 are present and full certification path could not be established after verifying MIDlet-Certificate-<1>-<m> certificates, repeatedly perform steps 1 and 2 for the value <n> greater by 1 than the previous value. The results of certificate verification are gathered into the Table 1.

Table 1. Actions upon completion of signer certificate verification.

Result | Action
--- | ---
Attempted to validate <n> paths. No public keys of the issuer for the certificate can be found or none of the certification paths can be validated | Authentication fails, JAR Installation is not allowed.
More than one full certificate path established and validated | Implementation proceeds with the signature verification using the first successfully verified certificate path is used for authentication and authorization.
Only one full certificate path established and validated | Implementation proceeds with the signature verification

### Verify the MIDlet Suite JAR

1. Get the public key from the verified signer certificate (above).
2. Get the `MIDlet-Jar-RSA-SHA1` attribute from the application descriptor.
3. Decode the attribute value from base64 yielding a PKCS #1 signature [RFC2437].
4. Use the signer's public key, signature, and SHA-1 digest of the JAR, to verify the signature. If the signature verification fails, reject the application descriptor and MIDlet suite. The implementation MUST NOT install the JAR on failure or allow MIDlets from the MIDlet suite to be invoked.

Once the steps of verifying the certificate, verifying the signature and verifying the JAR all succeed then the MIDlet suite contents are known to be intact and the identity of the signer is known. This process must be performed during installation.

#### Summary of MIDlet suite source verification results

It is essential that the steps performed to verify the digital signature as described above lead to the proof of the identity of the MIDlet suite signer. The results of the verification have a direct impact on authorization. The following, Table 2, summarizes the states to which the signature verification led and which are further used for authorization at install time.

Table 2. Summary of MIDlet suite source verification

Initial state | Verification result
--- | ---
JAD not present, JAR downloaded | Authentication can not be performed, may install JAR. MIDlet suite is treated as untrusted
JAD present but is JAR is unsigned | Authentication can not be performed, may install JAR. MIDlet suite is treated as untrusted
JAR signed but no root certificate present in the keystore to validate the certificate chain | Authentication can not be performed, JAR installation is not allowed
JAR signed, a certificate on the path is expired | Authentication can not be completed, JAR installation is not allowed
JAR signed, a certificate rejected for reasons other than expiration | JAD rejected, JAR installation is not allowed
JAR signed, certificate path validated but signature verification fails | JAD rejected, JAR installation is not allowed
JAR signed, certificate path validated, signature verified | JAR installation is allowed

### Caching of Authentication and Authorization Results

The implementation of the authentication and authorization process may store and transfer the results for subsequent use and MUST ensure that the cached information practically can not be tampered with or otherwise compromised between the time it is computed from the JAR, application descriptor, and authentication information and the authorization information is used.

It is essential that the MIDlet suite and security information used to authenticate and authorize a MIDlet suite is not compromised, for example, by use of removable media or other access to MIDlet suite storage that might be corrupted.

### Security in Split-VM Implementations

In environments that make use of a split VM (CLDC 5.4.6), it is possible to implement the security mechanism using JARs but this relies on converting the JAR to the device format when the JAR enters the network while faithfully preserving the semantics of the MIDlet. Once the conversion has happened, the device format of the application must be secured against tampering and retain its authorized permissions. This network security is often based on similar digital signature techniques to MIDlet security and it may be the case that this network security infrastructure is already present and active. If and only if this kind of network security infrastructure already exists and it can support all forms of protection required by this specification (and any future JSRs based on this specification), a permissible implementation of MIDlet Suite Security can be based on authenticating and authorizing the device format of the MIDlet since these implementation formats are the actual executable content that will be used on the device. The details of authenticating and authorizing a device format version of a MIDlet suite are implementation specific and thus not covered by this specification.

## MIDP X.509 Certificate Profile for Trusted MIDlet Suites

Secured trusted MIDlet suites utilize the same base certificate profile as does HTTPS. The profile is based on the WAP Certificate Profile, WAP-211-WAPCert-20010522-a [WAPCert] which is based on RFC2459 Internet X.509 Public Key Infrastructure Certificate and CRL Profile [RFC2459]. Refer to the package documentation for `javax.microedition.pki` for details.

### Certificate Processing for OTA

Devices MUST recognize the key usage extension and when present verify that the extension has the `digitalSignature` bit set. Devices MUST recognize the critical extended key usage extension and when present verify that the extension contains the `id-kp-codeSigning` object identifier (see RFC2459 sec. 4.2.1.13).

The application descriptor SHOULD NOT include a self-issued root certificate in a descriptor certificate chain. However MIDP devices SHOULD treat the certificate as any other in a chain and NOT explicitly reject a chain with a X.509v3 self-issued CA certificate in its chain.

### Certificate Expiration and Revocation

Expiration and revocation of certificates supplied in the application descriptor is checked during the authorization procedure, specifically during certificate path validation. Certificate expiration is checked locally on the device as such information is retrievable from the certificate itself. Certificate expiration verification is an intrinsic and mandatory part of certificate path validation.

Certificate revocation is a more complex check as it requires sending a request to a server and the decision is made based on the received response. Certificate revocation can be performed if the appropriate mechanism is implemented on the device. Such mechanisms are not part of MIDP implementation and hence do not form a part of MIDP 2.0 security framework.

If certificate revocation is implemented in the device, it SHOULD support Online Certificate Status protocol (OCSP) [RFC2560]. If other certificate revocation protocols are supported, support for these other protocols may indicate that a certificate has been revoked; in this case, it is permissible to consider the certificate as revoked regardless of the result returned by the OCSP protocol.

### Examples of MIDlet Suite Signing

There are many ways to structure protection domain root certificates and their associated signing policies. These examples are provided to illustrate some of the concepts in this specification and are not meant to limit the ways MIDlet PKI signing can be used. The examples allow MIDlets to be revoked (provided the device supports certificate revocation) but at differing granularities.

#### Example 1 - Developer Owns Signing Certificate

This encodes the origin of the MIDlet suite into the JAD (via the identity of the signer). If the certificate is revoked, all of the developer's signed MIDlets on every device for every user will have their execution permissions revoked.

1. Developer creates MIDlet network application
2. Developer encodes permissions into JAR manifest and creates final MIDlet JAR
3. Developer generates a private-public key pair with a signing certificate and has the certificate signed by one or more protection domain root certificates
4. The developer's certificate is used to sign the MIDlet JAR and create the associated JAD entries
5. MIDlet JAR can be distributed with a suitably populated JAD and run on a MIDP 2.0 compliant device with the appropriate protection domain root certificate

#### Example - Protection Domain Stakeholder Owns Signing Certificate

This encodes the signers identity (not the MIDlet suite developer) into the JAD. If the certificate is revoked, all MIDlets signed with this particular certificate will have their execution permissions revoked.

1. Developer creates MIDlet network application
2. Developer encodes permissions into JAR manifest and creates final MIDlet JAR
3. The protection domain stakeholder's signing certificate (not necessarily the root cert) is used to sign the MIDlet JAR and create the associated JAD entries
4. MIDlet JAR can be distributed with a suitably populated JAD and run on a MIDP 2.0 compliant device with the appropriate protection domain root certificate