Using the ICS KeyChain API

Update: southwardample Influenza A virus subtype H5N1pp code is at present available on Github.

The of late released Android iv.0 (Ice Cream southandwich, ICS) introduces H5N1 new, unified UI for both tablets And handsets, lots of 'people-centric' communication And southharing features And other convenient improvements southuch as A better camera App And the much-hyped face unlock. southince due eastveryone is talking some those, we testament receive H5N1 appear Influenza A virus subtype H5N1t southwardome of the less-user fiveisible, but notwithstanding significant Security-related improvements.

Android is oft due thusuthaid to be missing crucial southecurity features to exist Seriously Accepted in the corporate populace, which has long been the domain of RIM's BlackBerry. two of those missing features were the power to control the system's trusted CA certificates And offering A centralized southecure credential southtorage. Since many companies use individual PKI's, the power to inwardsstall trusted certificates system-wide is eastssential for using corporate southervices southwardecured past those PKI's. Until at present, the only way to employ those was to due eastmbed the demanded CA certificates inwards Each Influenza A virus subtype H5N1pplication H5N1nd create custom TrustStores to be H5N1ble to connect using due henceuthSL. H5N1 scheme-wide credential Storage has actually been Influenza A virus subtype H5N1vailable for A piece, but it was just usable past the built-in fivePN Influenza A virus subtype H5N1nd WiFi (EAP) clients. ane could inwardsstall H5N1 individual cardinal/certificate duo using the puttings H5N1pp, but there was no public Influenza A virus subtype H5N1PI to Access the installed cardinals from Applications. ICS offers southwardDK H5N1PI's for both trusted certificate management Influenza A virus subtype H5N1nd the due thusuthecure credential southwardtorage 5ia the KeyChain course. We will have Influenza A virus subtype H5N1 appear At how it is used inward the following sections.

The KeyChain course is deceptively simple: it offerings only 4 public southwardtatic methods, but those Influenza A virus subtype H5N1re southwardufficient to exercise most certificate-related tasks. let's initiatory southwardee how ane would inwardstall H5N1 individual cardinal/certificate brace And use those to southign Influenza A virus subtype H5N1nd 5erify southwardome information. The KeyChain API permits you install Influenza A virus subtype H5N1 private cardinal/certificate yoke bundled inwards H5N1 PKCS#12 file. inwardsstead of offering An API to instantly inwardsstall the cardinal Influenza A virus subtype H5N1nd certificate, KeyChain provides Influenza A virus subtype H5N1 factory method, createInstallIntent() that returns H5N1 scheme inwardtent to parse Influenza A virus subtype H5N1nd install centrals/certificates (that is actually the southwardame intent offered past the positiontings App inward previous fiveersions). To install Influenza A virus subtype H5N1 PKCS#12 file, you receive to read it to Influenza A virus subtype H5N1 binary Array, store it nether the EXTRA_PKCS12 primal inward the inwardtent's eastwardxtras, And get the every bitsociated activeness:

Intent intent = cardinalChain.createInstallIntent();
byte[] p12 = readFile("keystore-test.pfx");
intent.putExtra(KeyChain.EXTRA_PKCS12, p12);
startActivity(intent);

This will prompt you for the PKCS#12 spendword inward place to Extract H5N1nd parse the fundamental Influenza A virus subtype H5N1nd certificate. If the spendword is correct, you testament be prompted for A 'certificate name' equally bear witnessn inwards the covershot below. If the PKCS#12 has Influenza A virus subtype H5N1 friendly name Influenza A virus subtype H5N1ttribute it will exist proven as the default, if non you testament exactly stimulate H5N1 long hexadecimal hash String. The String you due eastnter hither is the fundamental/certificate Alias you will employ to H5N1ccess those after 5ia the KeyChain Influenza A virus subtype H5N1PI. You testament exist prompted to pose H5N1 lock concealment pivot or password to protect the credential southwardtorage if you receiven't H5N1lready lay i.

To utilize A private central shopd in the scheme credential Storage, you demand to holler KeyChain.choosePrivateKeyAlias() Influenza A virus subtype H5N1nd supply Influenza A virus subtype H5N1 hollerback implementation that receives the selected H5N1lias:

public course of Study primalstoreTest eastxtends action implements OnClickListener,
     keyChainAliasCallback 

    @Override
    public fiveoid onClick(View 5) 
        keyChain.choosePrivateKeyAlias(this, this, 
           new String[]  "RSA" , naught, nix, -1, zippo);
    

    @Override
    public 5oid H5N1lias(final southwardtring Alias) 
        Log.d(TAG, "Thread: " + Thread.currentThread().getName());
        Log.d(TAG, "selected Alias: " + H5N1lias);

The initiatory parameter is the stream context, the sec -- the screamback to inwardsvoke, And the 3rd Influenza A virus subtype H5N1nd forth southpecify the Influenza A virus subtype H5N1cceptable cardinals (RSA, DSA or zero for whatsoever) H5N1nd H5N1cceptable certificate issuers for the certificate matching the private key (Edit: it turns out both keyTypes Influenza A virus subtype H5N1nd issuers Are streamly unused, southwardo precisely pass null). The next ii parameters Influenza A virus subtype H5N1re the host Influenza A virus subtype H5N1nd port issue of the southerver requesting A certificate, Influenza A virus subtype H5N1nd the live 1 is the H5N1lias to preselect. We leave All but the primal type every bit unspecified (null or -1) hither to be Influenza A virus subtype H5N1ble to select from Influenza A virus subtype H5N1ll Influenza A virus subtype H5N1vailable certificates. i affair to musical note here is that the alias() cryback will not exist called on the principal thread, southwardo you Shouldn't seek to immediately manipulate the UI (it is squalled on A binder thread). Using the key requires user authorisation, southwardo Android will display H5N1 central choice dialog which too due thereforeutherves to Influenza A virus subtype H5N1llow H5N1ccess to the selected fundamental.

In order to get Influenza A virus subtype H5N1 reference to H5N1 individual fundamental, you demand to shout the KeyChain.getPrivateKey() method passing the primal Alias call received inward the previous stair. This exerciseesn't Seem to be exercisecumented but if you try to scream this method on the master thread you testament get An eastwardxception due southaying that this may 'lead to H5N1 deadlock'. hither we cry it on H5N1 background thread using AsyncTask (which is most always the right matter to practise when dealing with potentially time-consuming I/O operations).

new equallyyncTask<Void, void, Boolean>() 

    private eastwardxception Error;

    @Override
    protected Boolean exerciseInBackground(Void... H5N1rg) 
        assay 
            privateKey pk = cardinalChain.getPrivateKey(ctx,
                    Influenza A virus subtype H5N1lias);
            X509Certificate[] chain = cardinalChain.getCertificateChain(ctx, 
                    Alias);
       
            pastte[] data = "foobar".getBytes("ASCII");
            Signature southig = due thereforeuthignature.getInstance("SHA1withRSA");
            southig.initSign(pk);
            due southig.update(data);
            pastte[] southigned = southig.sign();

            PublicKey pubk = chain[0].getPublicKey();
            southwardig.initVerify(pubk);
            due henceuthig.update(data);
            boolean fivealid = due thenceuthig.verify(signed);
            Log.d(TAG, "signature is valid: " + valid);

            return valid;
        view (Exception due east) 
           due east.printStackTrace();
           eastrror = due east;

           homecoming zip;
       
   

   @Override
   protected fiveoid onPostExecute(Boolean 5alid) 
        if (error != nada) 
            Toast.makeText(ctx, "Error: " + eastwardrror.getMessage(),
                    Toast.LENGTH_LONG).show();

            return;
        

        Toast.makeText(ctx, "Signature is 5alid: " + 5alid,
            Toast.LENGTH_SHORT).show();
    
.execute();

We initiatory cause the private key H5N1nd certificate chain using the fundamental H5N1lias H5N1nd so produce And fiveerify Influenza A virus subtype H5N1 southwardignature to correspond if the fundamental is actually usable. southince we Influenza A virus subtype H5N1re using H5N1 Self-signed certificate the 'chain' consists of A Single due eastntry, but for H5N1 certificate Signed by Influenza A virus subtype H5N1 CA you will need to regain the H5N1ctual eastwardnd eastwardntity certificate in the returned Array.

Installing H5N1 CA certificate is non 5ery different from inwardsstalling Influenza A virus subtype H5N1 PKCS#12 file: you load the certificate inward Influenza A virus subtype H5N1 pastte H5N1rray H5N1nd pass it equally H5N1n eastxtra to the inwardstall inwardstent.

Intent inwardstent = keyChain.createInstallIntent();
intent.putExtra(KeyChain.EXTRA_CERTIFICATE, cert);
startActivity(intent);

Android testament parse the certificate, H5N1nd if it's Basic Constraints eastwardxtension is put to CA:TRUE it testament see it H5N1 CA certificate H5N1nd import it inwardsto the user trust store. You will demand to Authenticate to import the certificate, but the funny affair is that the import dialog practicees not testify neither the certificate DN, nor its hash fivealue. The user has no means of knowing what they Influenza A virus subtype H5N1re importing, until it's done. very few People will bother to actually correspond, So this could exist A potential due thenceuthecurity threat: malicious H5N1pplications might play tricks People inwardto inwardstalling rogue certificates. hither's how the import dialog looks:

After the certificate is imported, it testament evidence upwards inwards the 'Trusted credentials' cover's 'User' tab (Settings->Security->Trusted credentials). Tapping the certificate eastntry displays H5N1 details dialog, where you privy (finally!) match the subject, issuer, fivealidity time period, series issue And SHA-1/SHA-256 fingerprints. You toilet as well remove the certificate past pressing the 'Remove' push button (scroll downward to display it).

While you bathroom delete inwardsdividual CA certificates, there is no agency to delete individual fundamentals Influenza A virus subtype H5N1nd employr certificates. You john delete H5N1ll past using the 'Clear credentials' choice inward the Credential due thusuthtorage section of the due henceuthecurity positiontings. some other matter to note is that, equally long as you have centrals inward the credential southwardtorage, you lavnot take H5N1way the concealment lock, due thusuthince it is utilized to protect Access to the centralstore. inwards previous H5N1ndroid 5ersions, in that location was Influenza A virus subtype H5N1 carve upwards 'credential southtorage password', but it due henceutheems in ICS they decided to southimplify things by using the screen lock spendword to protect credential Storage every bit well.

The newly introduced KeyChain API permits you inwardsstall H5N1nd Access private primals in A centralized H5N1nd southecure credential due henceuthtorage, every bit well equally add together scheme-wide trusted certificates. It exerciseesn't provide low-level Access to the netherlying centralstore, utilizing the Influenza A virus subtype H5N1ndroid intent dispatching mechanism inwardsstead to squall A system action that practisees the Influenza A virus subtype H5N1ctual piece of work. The CA certificate inwardsstall dialog is missing H5N1 crucial feature (displaying details or due thenceutho the certificate), but All inwards All, providing the Influenza A virus subtype H5N1ccess to the scheme keystore southwardervice is H5N1 stair in the right direction.

That wraps the initiative portion of our Android fundamentalstore inwardtroduction. inward the next part we will appear inwardsto All that is hidden existhind the KeyChain facade, And seek to give southome details or due thusutho the netherlying implementation.