About access control files

Access control files (ACFs) describe the access rights of applications to connect to applets on the UICC Secure Element (SE).

The ACF is used to:

Protect the applets on the UICC SE from being accessed by applications that do not have permission to access it. For example, an ACF can prevent a third-party application from being loaded onto a device and attempting to get information from the Visa applet on the SE.
Disallow card transaction information to be delivered to applications on the device which do not have permission to access the transactions. For example, an ACF can prevent a Bank X MasterCard applet from listening for Bank Y MasterCard transactions.

Access control file behavior

BlackBerry 10 devices support access control using the GlobalPlatform (GP) and the Gemalto access control applets.

The BlackBerry 10 platform performs a series of ACF checks, using cached ACF data, to determine whether to grant or deny an application access to an applet when:

An application attempts to connect to an applet on the SE
A card transaction is completed by an applet and the platform needs to deliver transaction notifications to the appropriate applications

To describe the details of the ACF verification process, we use the case of an application attempting to connect to an applet as an example. Note that the developer must sign the BAR file and install the application on the device.

When an app attempts to connect to an applet on the SE, the platform verifies that:

A supported applet exists. This check is completed in a particular order as described in the section below.
The app has a valid signature (see Sign the BAR file). If no signature is found or if the app signature is not valid, the app can access a particular applet only if the ACF rules allow any unsigned app to access that applet.
The ACF rules permit the app to access the applet.
The app has a valid RSA-based certificate or certificate chain. If the app is not signed with an RSA-based certificate or certificate chain, access is granted only if the ACF rule allows all certificates to pass.

Verify the access control applets

The platform verifies the access control applets in the following order and builds the ACF cache in the process.

GP applet (AID: A0.00.00.01.51.41.43.4C.00)
PKCS #15 applet (AID: A0.00.00.00.63.50.4B.43.53.2D.31.35)
Gemalto applet (AID: A0.00.00.00.18.47.50.41.43.2D.31.35)

The GP applet is checked if it is available. If the applet is not present, a fall-through mechanism chooses the PKCS #15 applet.

If the PKCS #15 applet is used, the applet itself and the object identifier (OID 1.2.840.114283.200.1.1) in the Data Object Directory File (DODF) must be present. Otherwise, the fall-through mechanism chooses the Gemalto applet.

If the Gemalto applet is used, the applet itself and the OID (1.2.840.114283.200.1.1) in the DODF must be present.

If none of the application identifiers (AIDs) above is found, or if the OIDs (in the case of PKCS #15 and Gemalto) are not present, or if there is a structural error in the ACF scheme itself, no ACF cache is built and access is denied.

Although the Gemalto specifications state that the EFdir file should be checked if the main Gemalto and PKCS #15 AIDs are not found, we do not specifically enforce this rule.

The GP and Gemalto AIDs are proprietary, while the PKCS #15 AID is not.

It is possible for a carrier to customize the ordering in which the platform checks the above access control file schemes, or to even have certain schemes ignored. This customization is performed by associating a certain ordering with a specific set of mobile country codes and/or mobile network codes (MCC/MNC). When a UICC is inserted into a device, the MCC/MNC are read from the UICC, and if any custom access control ordering rules need to be enforced for that specific MCC/MNC, that custom ordering will be used instead of the default order listed above.

Only the owners of a UICC (for example, carriers) can request this customization. To request customization, the carrier should consult the appropriate carrier technical manager at BlackBerry.

Differences between BlackBerry 7 and BlackBerry 10

There are some differences in ACF behavior between BlackBerry 7 and BlackBerry 10:

BlackBerry 10 supports only the ACF schemes described above. If these schemes are not found, access is denied.
BlackBerry 10 does not support other schemes, such as SATSA Appendix A, which are supported by BlackBerry 7.

Sign the BAR file for an application that requires access to the secure element

The BlackBerry 10 Native SDK contains the tools you need to build and sign a BAR file that requires access to the secure element. BAR files must be signed using an RSA based certificate or certificate chain.

You need the BlackBerry 10 Native SDK to sign BAR files using RSA certificates. To sign a BAR file, you create a keystore, then use the blackberry-signer command to sign the BAR file. The following steps demonstrate how to sign a BAR file using the command line.

Open a command prompt on your development computer.
Navigate to where the Native SDK is installed on your computer.
Execute the bbndk-env.bat (or bbndk-env.sh for Linux or Mac OS) file to set paths correctly in your command prompt.
Create the certificate(s) using a certificate-generating tool, such as OpenSSL. The certificate is used to sign the BAR file.
For example, here is how to generate a PKCS#12 keystore using OpenSSL:
```
# openssl genrsa -des3 -out selfsign.key 1024
# openssl req -config C:\OpenSSL-Win32\bin\openssl.cfg -new -key selfsign.key -out selfsign.csr
# openssl x509 -req -days 365 -in selfsign.csr -signkey selfsign.key -out selfsign.crt
# openssl pkcs12 -export -in selfsign.crt -inkey selfsign.key -name REAL_ALIAS -out selfsign.p12
```
In the above commands, you need to:
- Replace selfsign with the name of your output file generated by each command.
- Replace REAL_ALIAS with the desired alias to be used for the key in the selfsign.p12 file.
Use the blackberry-signer utility to sign your BAR file.
```
# blackberry-signer -keystore selfsign.p12 -sigfile GPACACF -sigalg SHA512withRSA -storepass YOUR_PASSWORD -verbose YOUR_BAR_FILE.bar REAL_ALIAS
```
In the above command,
- You need to replace selfsign.p12 with the name of your .p12 file.
- The -sigalg SHA512withRSA argument specifies using SHA-512 with RSA as the signing algorithm. This combination is mandatory.
- The –storepass YOUR_PASSWORD argument is mandatory if your .p12 file is password protected. Replace YOUR_PASSWORD with the password of your .p12 file. This argument must appear before the .bar filename argument.
- You need to replace YOUR_BAR_FILE.bar with the name of your .bar file.
- You need to replace REAL_ALIAS with the alias of the key within your .p12 file.
This command generates two new files, GPACACF.SF and GPACACF.RSA, and inserts them into the META-INF folder of your BAR file. GPACACF.SF is a text file that contains a list of all files in the BAR file as well as an SHA-512 hash of each file. The GPACACF.RSA file contains a signature generated by signing the GPACACF.SF file with your private key, and also contains your ACF certificate chain. In effect, the signer command above signs all of the files in your BAR file.

Older versions of the BlackBerry 10 Native SDK do not support the signing command above. If you're using an older version of the BlackBerry 10 Native SDK, you can either download the latest version or use the command below to sign your BAR file.
```
# blackberry-signer -keystore selfsign.p12 -storetype pkcs12 -sigalg SHA512withRSA –storepass YOUR_PASSWORD -verbose YOUR_BAR_FILE.bar GPACACF
```
Obtain an SHA-1 hash of your RSA certificate. To do this:
1. Create a binary copy of your certificate.
```
# openssl base64 -d -out selfsign.bin -in selfsign.crt
```
2. Check that the binary copy looks like a certificate. That is, it starts with 0x30 and contains the certificate text.
```
# xxd selfsign.bin
```
3. Use OpenSSL to generate an SHA-1 hash of the certificate.
```
# openssl sha1 selfsign.bin
```
Send the SHA-1 hash to the person in charge of the ACF on your secure element.