Wednesday, October 19, 2016
Unifying Key Store Access in ICS
Unifying Key Store Access in ICS
[This post is a group effort by Tony Chan, Fred Chung, Brian Carlstrom, and Kenny Root. — Tim Bray]
Android 4.0 (ICS) comes with a number of enhancements that make it easier for people to bring their personal Android devices to work. In this post, we’re going to have a look at the key store functionality.
Back in Android 1.6 (Donut), a system key store was added for use by VPN. Although this was later expanded to support WiFi authentication, applications weren’t able to access it.
In the past, it was common practice for apps to maintain their own key store if they needed to authenticate a secure SSL web server, or authenticate the user to a server via a client certificate. While this works, it can present manageability issues in an enterprise environment where multiple certificates may be shared across a number of apps such as Email and Browser.
New in ICS: KeyChain
To bridge the gap in ICS, there’s a new API named KeyChain that regulates application access to the system key store and allows users to grant application access to the credentials stored there. Additionally, this API enables applications to initiate installation of credentials from X.509 certificates and PKCS#12 key stores.
The KeyChain API is rather simple. To install a key store or a certificate, you retrieve an install intent, supply the raw bytes of the credentials, and use the intent to launch a system installation dialog. If it’s a keystore, as in the example below, you’ll need provide the data in PKCS#12 format, and the user will have to know the PKCS#12 password.
byte[] keystore = . . (read from a PKCS#12 keystore)
Intent installIntent = KeyChain.createInstallIntent();
installIntent.putExtra(KeyChain.EXTRA_PKCS12, keystore);
startActivityForResult(installIntent, INSTALL_KEYSTORE_CODE);The install intent launches a system dialog that prompts the user to enter the password for the keystore.
This can also be used for installing organizational CA certificates which will then be trusted by all applications to authenticate to non-public servers with certificates issued by the same CA.
In ICS, Android no longer requires a separate password to protect the system credential storage. Rather, it uses the screen lock password for this purpose, and the Android Device Administration API can be used for central policy enforcement. This means, for example, that the screen lock password can’t be removed as long as the secured credentials remain on the device.
Accessing System Key Store Credentials
Once the system key store is configured, the KeyChain API offers functions such as requesting a client certificate for authenticating with an SSL server. The first time an application requests access, the user is prompted with a list of available certificates and can select one to grant access to that certificate to the application. If the user chooses to allow access to a certificate, a string alias name for the certificate is returned to the application. The application can then use the alias to access the certificate in the future without further user involvement.
The code below illustrates how an application can prompt the user to select a credential alias and grant access to the application. KeyChain will remember this selection such that the same application can save the credential alias selection and have access to the same certificate in future. For example, the Email application for ICS has implemented this feature in its Server Settings screen.
KeyChain.choosePrivateKeyAlias(this,
new KeyChainAliasCallback() {
public void alias(String alias) {
// Credential alias selected. Remember the alias selection for future use.
if (alias != null) saveAlias(alias);
}
},
new String[] {"RSA", "DSA"}, // List of acceptable key types. null for any
null, // issuer, null for any
"internal.example.com", // host name of server requesting the cert, null if unavailable
443, // port of server requesting the cert, -1 if unavailable
null); // alias to preselect, null if unavailable
Once an application has been granted access to the certificate, it can access the private key through the getPrivateKey() method. It is worth noting that as with any PrivateKey objects, the application should not make assumptions about the encoding. For example, on some implementations the PrivateKey object may just be an opaque representation of a key stored in a hardware key store.
Here’s a sample code snippet that demonstrates the use of private key retrieved from the key store for signing:
PrivateKey privateKey = KeyChain.getPrivateKey(context, savedAlias);
if (privateKey != null) {
...
Signature signature = Signature.getInstance("SHA1withRSA");
signature.initSign(privateKey);
...
}A common use of the private key is for SSL client authentication. This can be implemented by using an HttpsURLConnection with a custom X509KeyManager that returns the PrivateKey retrieved from the KeyChain API. The open source Email application for ICS uses KeyChain with an X509ExtendedKeyManager. To learn more, have a look at the source code (in SSLUtils.java).
This API provides a unified way to access the system key store credentials. If your application uses client certificates (take note: enterprise email client or web browser developers) you should definitely look into the KeyChain API for your next update!
Available link for download
Wednesday, September 14, 2016
New Social APIs in Android ICS
New Social APIs in Android ICS
[This post is by Daniel Lehmann, Tech Lead on the Android Apps team. — Tim Bray]
[We’re trying something new; There’s a post over on Google+ where we’ll host a discussion of this article. Daniel Lehmann has agreed to drop by and participate. Come on over and join in!]
With Android Ice Cream Sandwich, we set out to build software that supports emotional connections between humans and the devices they carry. We wanted to build the most personal device that the user has ever owned.
The first ingredient in our recipe is to show users the people that they care about most in a magazine-like way. High-resolution photos replace simple lists of text.
The second ingredient is to more prominently visualize their friends’ activities. We show updates from multiple sources wherever a contact is displayed, without the need to open each social networking app individually.
Android is an open platform, and in Ice Cream Sandwich we provide a rich new API to allow any social networking application to integrate with the system. This post explains how apps like Google+ use these APIs, and how other social networks can do the same.
A few basics
Since Eclair (Android 2.0), the system has been able to join contacts from different sources. Android can notice if you are connected to the same person and different networks, and join those into aggregate contacts.
Essential terms to understand throughout the remainder of this post are:
RawContact is a contact as it exists in one source, for example a friend in Skype.
Data rows exists for each piece of information that the raw contact contains (name, phone number, email address, etc.).
A Contact joins multiple raw contacts into one aggregate. This is what the user perceives as a real contact in the People and Phone apps.
A sync adapter synchronizes its raw contacts with its cloud source. It can be bundled with a Market application (examples: Skype, Twitter, Google+).
While users deal with contacts, sync adapters work with their raw contact rows. They own the data inside a raw contact, but by design it is left up to Android to properly join raw contact rows with others.
Contacts sync adapters have a special xml file that describes their content, which is documented in the Android SDK. In the following paragraphs, we’ll assume this file is named contacts.xml.
The Android SDK also contains the application SampleSyncAdapter (and its source code) that implements everything mentioned in here in an easy to understand way.
High resolution photos
In Android versions prior to Honeycomb (3.0), contact photos used to be 96x96. Starting with ICS, they now have a thumbnail (which is the 96x96 version) and a display photo. The display photo’s maximum size can vary from device to device (On Galaxy Nexus and Nexus S, it is currently configured to be 256x256, but expect this to vary with future devices). The size as configured can be queried like this:
private static int getPhotoPickSize(Context context) {
// Note that this URI is safe to call on the UI thread.
Cursor c = context.getContentResolver().query(DisplayPhoto.CONTENT_MAX_DIMENSIONS_URI,
new String[]{ DisplayPhoto.DISPLAY_MAX_DIM }, null, null, null);
try {
c.moveToFirst();
return c.getInt(0);
} finally {
c.close();
}
}This value is useful if you need to query the picture from the server (as you can specify the right size for the download). If you already have a high resolution picture, there is no need for any resizing on your side; if it is too big, the contacts provider will downsample it automatically.
Up until now, pictures were written using a ContentValues object, just like all the other data rows of the raw contact. While this approach is still supported, it might fail when used with bigger pictures, as there is a size limit when sending ContentValues across process boundaries. The prefered way now is to use an AssetFileDescriptor and write them using a FileOutputStream instead:
private static void saveBitmapToRawContact(Context context, long rawContactId, byte[] photo) throws IOException {
Uri rawContactUri = ContentUris.withAppendedId(RawContacts.CONTENT_URI, rawContactId);
Uri outputFileUri =
Uri.withAppendedPath(rawContactUri, RawContacts.DisplayPhoto.CONTENT_DIRECTORY);
AssetFileDescriptor descriptor = context.getContentResolver().openAssetFileDescriptor(
outputFileUri, "rw");
FileOutputStream stream = descriptor.createOutputStream();
try {
stream.write(photo);
} finally {
stream.close();
descriptor.close();
}
}For best results, store uncompressed square photos and let the contacts provider take care of compressing the photo. It will create both a thumbnail and a display photo as necessary.
This API is available on API version 14+. For older versions, we recommend to fallback to the old method using ContentValues and assuming a constant size of 96x96.
Update streams
The API for update streams is the biggest new addition for contacts in Ice Cream Sandwich. Sync adapters can now enrich their contact data by providing a social stream that includes text and photos.
This API is intended to provide an entry point into your social app to increase user engagement. We chose to only surface the most recent few stream items, as we believe that your social app will always be the best way to interact with posts on your network.
StreamItems rows are associated with a raw contact row. They contain the newest updates of that raw contact, along with text, time stamp and comments. They can also have pictures, which are stored in StreamItemPhotos. The number of stream items per raw contact has a limit, which on the current Nexus devices is set to 5, but expect this number to change with future devices. The limit can be queried like this:
private static int getStreamItemLimit(Context context) {
// Note that this URI is safe to call on the UI thread.
Cursor c = context.getContentResolver().query(StreamItems.CONTENT_LIMIT_URI,
new String[]{ StreamItems.MAX_ITEMS }, null, null, null);
try {
c.moveToFirst();
return c.getInt(0);
} finally {
c.close();
}
}When displayed in the People app, stream items from all participating raw contacts will be intermixed and shown chronologically.
The following function shows how to add a stream item to an existing raw contact:
private static void addContactStreamItem(Context context, long rawContactId, String text,
String comments, long timestamp, String accountName, String accountType){
ContentValues values = new ContentValues();
values.put(StreamItems.RAW_CONTACT_ID, rawContactId);
values.put(StreamItems.TEXT, "Breakfasted at Tiffanys");
values.put(StreamItems.TIMESTAMP, timestamp);
values.put(StreamItems.COMMENTS, comments);
values.put(StreamItems.ACCOUNT_NAME, accountName);
values.put(StreamItems.ACCOUNT_TYPE, accountType);
context.getContentResolver().insert(StreamItems.CONTENT_URI, values);
}You can also specify an action that should be executed when a stream item or one of its photos is tapped. To achieve this, specify the receiving Activities in your contacts.xml using the tags viewStreamItemActivity and viewStreamItemPhotoActivity:
<ContactsAccountType
viewStreamItemActivity="com.example.activities.ViewStreamItemActivity”
viewStreamItemPhotoActivity="com.example.activities.ViewStreamItemPhotoActivity">
<!-- Description of your data types -->
</ContactsAccountType>Update streams are available on API version 15+ and are intended to replace the StatusUpdate API. For previous versions, we recommend that you fall back to the StatusUpdates API, which only shows a single text item and no pictures.
“Me” profile
Ice Cream Sandwich is the first version of Android that supports the “Me” contact, which is prominently shown at the top of the list of the new People app. This simplifies use-cases that used to be a multi-tap process in previous versions — for example, sharing personal contact data with another person or “navigating home” in a navigation app. Also it allows applications to directly address the user by name and show their photo.
The “Me” profile is protected by the new permissions READ_PROFILE and WRITE_PROFILE. The new functionality is powerful; READ_PROFILE lets developers access users’ personally identifying information. Please make sure to inform the user on why you require this permission.
The entry point to the new API is ContactsContract.Profile and is available on API version 14+.
Add connection
Previously, connecting with users on a social network involved opening the respective social networking app, searching for the person and then connecting (“Friend”, “Follow” etc.). Ice Cream Sandwich has a much slicker approach: When looking at an existing contact in the People application, the user can decide to add this person to another network as well. For example, the user might want to follow a person on Google+ that they already have as a contact in Gmail.
Once the user taps one of the “Add connection” commands, the app is launched and can look for the person using the information that is already in the contact. Search criteria are up to the app, but good candidates are name, email address or phone number.
To specify your “Add connection” menu item, use the attributes inviteContactActivity and inviteContactActionLabel in your contacts.xml:
<ContactsAccountType
inviteContactActivity="com.example.activities.InviteContactActivity"
inviteContactActionLabel="@string/invite_action_label">
<!-- Description of your data types -->
</ContactsAccountType>Be sure to use the same verb as you typically use for adding connections, so that in combination with your app icon the user understands which application is about to be launched.
The “Add connection” functionality is available on API version 14+.
Contact-view notification
High-resolution pictures need a lot of space, and social streams quickly become outdated. It is therefore not a good idea to keep the whole contacts database completely in sync with the social network. A well-written sync adapter should take importance of contacts into account; as an example, starred contacts are shown with big pictures, so high-resolution pictures are more important. Your network might also have its own metrics that can help to identify important contacts.
For all other contacts, you can register to receive a notification which is sent by the People app to all sync adapters that contribute to a contact whenever the contact’s detail page is opened. At that point, you can provide additional information. As an example, when the Google+ sync adapter receives this notification, it pulls in the high-resolution photo and most recent social stream posts for that user and writes them to the contacts provider. This can be achieved by adding the viewContactNotifyService attribute to contacts.xml:
<ContactsAccountType
viewContactNotifyService="com.example.notifier.NotifierService">
<!-- Description of your data types -->
</ContactsAccountType>When this Intent is launched, its data field will point to the URI of the raw contact that was opened.
These notifications are available with API version 14+.
Summary
With Ice Cream Sandwich, we improved key areas around high resolution photos and update streams, and simplified the creation of new connections.
Everything outlined in here is done using open APIs that can be implemented by any network that wants to participate. We’re excited to see how developers take advantage of these new features!
Available link for download