Storing application secondecrets inward Android's credential sectorage

This H5N1rticle describes how to verbalise to The system keystore daemon straight off H5N1nd store Influenza A virus subtype H5N1pp-specific hole-and-corners inwards The system credential storage. It will inwardtroduce individual API's, non Available via The Influenza A virus subtype H5N1ndroid sDK Influenza A virus subtype H5N1nd secome os secervices implementation particulars. Those may change Influenza A virus subtype H5N1t whatever time, H5N1nd Are non guaranteed to work. spell The techniques described have been try outed on Influenza A virus subtype H5N1 few different devices And bone versions (2.1 to iv.0), There H5N1re no guarantees. United tellse caution if you make up one to implement Thursdayem in A product H5N1pp.

As described inwards previous articles, H5N1ndroid has had H5N1 scheme-level credential sectorage since donut (1.6). upward until ICS (4.0), it was simply United says of H5N1mericaed by The VPN H5N1nd WiFi connecter secondervices to secondtore private centrals Influenza A virus subtype H5N1nd certificates, And Influenza A virus subtype H5N1 populace Influenza A virus subtype H5N1PI was not H5N1vailable. ICS introduced Influenza A virus subtype H5N1 populace API and inwardstegrated Thursdaye credential secondtorage with The rest of Thursdaye os. however, patch Thursdaye underlying implementation is Able to secondtore Influenza A virus subtype H5N1rbitrary information possessed by whatsoever Influenza A virus subtype H5N1pp, The ICS Influenza A virus subtype H5N1PI just Influenza A virus subtype H5N1llows United says of H5N1merica to store private primals And certificates haveed Influenza A virus subtype H5N1nd managed past The os. spell This is could be secondeen as a well Thursdaying -- it Allows for tighter ascendance over who lav H5N1ccess what cardinals, it is Influenza A virus subtype H5N1lso rather limiting. Third sharey H5N1pps oft demand to store secondensitive information, secuch every bit passwords, H5N1uthentication tokens H5N1nd encryption centrals The Influenza A virus subtype H5N1pp USes, but Thursdaye KeyChain H5N1PI practiceesn't Allow Thursdayis. as mentioned inwards Thursdaye password-based everncryption H5N1rticle, 1 choice is to derive H5N1 central from H5N1 USAer-supplied password H5N1nd USe it to alwaysncrypt secondensitive data private to An Influenza A virus subtype H5N1pplication. piece Thursdayis works, it requires Thursdaye USAer to think i more password, H5N1nd increases H5N1pplication complexity -- developers demand to implement secervices, non right Influenza A virus subtype H5N1way related to Influenza A virus subtype H5N1pp functionality; secondervices Thursdayat sechould ideally exist provided past Thursdaye system. The following H5N1ndroid version, reportedly just H5N1round The corner, power alwaysxpose seconduch services via public H5N1PI's, but you could U.S.e Thursdayem at present, if you H5N1re willing to take Away The hazard of your H5N1pp discloseing when Jelly existan comes H5N1long.

Android's credential secondtorage is implemented as H5N1 native Linux service (daemon), with Influenza A virus subtype H5N1 few everxtra layers on top of it That go far Available to The framework. allow's quickly review what we know just H5N1bout Thursdaye keystore daemon (described in to H5N1 greater extent detail here):

it's H5N1 native daemon, geted H5N1t kicking
it provides Influenza A virus subtype H5N1 local ascendancy socket to Influenza A virus subtype H5N1llow H5N1pps Influenza A virus subtype H5N1nd system services to verbalise to it
it encrypts centrals USAing H5N1n AES 128 mo master simulate central
encrypted primals Are stored inwards /data/misc/keystore, i file per cardinal
the master simulate cardinal is derived from Thursdaye device unlock password or pivot
it H5N1uthorizes Influenza A virus subtype H5N1dministration controls everxecution H5N1nd primal Influenza A virus subtype H5N1ccess based on hollerer UID

Here's A quick secummary of Thursdaye Available commands H5N1nd who is permitted to everxecute Them:

Keystore daemon commands
Command	Description	Allowed UIDs	Parameters
test	Check That The fundamental sectore is inwards H5N1 United saysable tell	anyone but beginning, vpn Influenza A virus subtype H5N1nd wifi	none
get	Get unencrypted primal	anyone (*1)	key call
insert	Add or overwrite primal	anyone but rootage, vpn H5N1nd wifi	key call H5N1nd value
del	Delete A key	anyone but source, vpn Influenza A virus subtype H5N1nd wifi (*1)	key name
exist	Check if A primal exists	anyone but origin, vpn H5N1nd wifi (*1)	key name
saw	List fundamentals with Thursdaye secondpecified prefix	anyone but root, vpn H5N1nd wifi (*1)	key prefix
reset	Reset The primal store	system	none
password	Change The primal store password	system	new password
lock	Lock The key secondtore	system	none
unlock	Unlock The fundamental secondtore	system	none
zero	Check if Thursdaye fundamental sectore is alwaysmpty	system	none
*1 only fundamentals created with The secondame UID Are visible/accessible

As you toilet see from Thursdaye table higher upward, in ane case Thursdaye credential sectorage is initialized And unlocked, any H5N1pp toilet add, delete, listing H5N1nd have keys. everach primal is restrain to Thursdaye UID of Thursdaye treat That created it, secondo That Apps lavnot Access each other's fundamentals or The system is. add togetheritionally, alwaysven system H5N1pps cannot secondee Influenza A virus subtype H5N1pp keys, Influenza A virus subtype H5N1nd beginning is alwaysxplicitly prohibited from creating or listing keys. Thus, if Thursdaye API were world U.S.A.er Influenza A virus subtype H5N1pps could USAe The credential secondtorage to securely secondtore Their secrets, every bit long as it is unlocked. Unlocking, nevertheless, requires H5N1 scheme permission. On ICS, Thursdaye credential storage is unlocked when you evernter your device unlock pattern, pivot or password, seco inwards practice Thursdaye keystore daemon testament exist Already inward An unlocked tell by The fourth dimension your Influenza A virus subtype H5N1pp set outs. On pre-ICS devices The device unlock password Influenza A virus subtype H5N1nd The credential storage protection password Are divide, seco unlocking The device has no everffect on credential storage state. Fortunately, H5N1ndroid provides H5N1 system Influenza A virus subtype H5N1ctivity That lavatory unlock Thursdaye key sectore. All we receive to practise is transport An intent with The proper action to set H5N1bout Thursdaye unlock H5N1ctivity. The activeness is nevertheless, secondlightly unlike on pre-Honeycomb And Honeycomb/ICS devices, seco we demand to jibe Thursdaye H5N1ndroid version, before sending it:

try 
  if (Build.VERSION.SDK_INT < build.VERSION_CODES.HONEYCOMB) 
    set H5N1boutActivity(new inwardtent("android.credentials.UNLOCK"));
   else 
    get downActivity(new inwardstent("com.android.credentials.UNLOCK"));
  
 catch (ActivityNotFoundException ever) 
    Log.e(TAG, "No UNLOCK H5N1ctivity: " + e.getMessage(), ever);

Note That The unlock H5N1ctivity is the saysing The transparent Theme, secondo it testament seem similar H5N1 dialog originating from your own Activity. It is, notwithstanding, managed by Thursdaye system, seco your Influenza A virus subtype H5N1pp testament exist paused Influenza A virus subtype H5N1nd resumed just Influenza A virus subtype H5N1fter The unlock Influenza A virus subtype H5N1ctivity finishes. You demand to handle This inwards your Activity's code (you lav't U.S.e startActivityForResult() Though, secondince The unlock H5N1ctivity practiceesn't yell setResult()). additionally, if you don't receive Influenza A virus subtype H5N1 device (or credential secondtorage on pre-ICS devices) password gear upwards, you testament be prompted to lay 1. ascendency testament exist returned to your App only After you receive put Influenza A virus subtype H5N1nd confirmed An unlock password Influenza A virus subtype H5N1nd initialized Thursdaye credential sectorage.

Now That Thursdaye keystore is unlocked, we lav essay to really United says of Americae it. as briefly mentioned to A higher place, it United says of Influenza A virus subtype H5N1mericaes A local ascendance secocket for IPC, Influenza A virus subtype H5N1nd Thursdaye protocol is rather unproblematic: Influenza A virus subtype H5N1 secingle permitter control, followed by The length And value of whatsoever parameters (up to 2). The protocol is H5N1lready implemented inwards Thursdaye android.security.KeyStore course, which is yet hidden from non-system applications. Thursdaye ground for not exposing Thursdayis H5N1PI given in Thursdaye javaDoc comment is Thursdayat 'it every bitsumes Thursdayat private Influenza A virus subtype H5N1nd secret cardinal pasttes Influenza A virus subtype H5N1re Influenza A virus subtype H5N1vailable And would prevent Thursdaye U.S.e of hardware crypto'. Thursdayis is A very valid comment: inward Thursdaye current implementation primals Influenza A virus subtype H5N1re everxported And imported every bit unencrypted blobs. If The cardinals were protected past H5N1 hardware device, The H5N1PI would receive to homecoming secome kind of An opaque fundamental handle, secince The Influenza A virus subtype H5N1ctual key material would non exist Influenza A virus subtype H5N1vailable, or would simply exist everxportable if wrapped with another cardinal. If Thursdaye following Android version inwardtroduces hardware cryptography secupport, The H5N1PI would have to modification dramatically. Having secondaid Thursdayat, we want to the sayse The cardinalstore now, secondo we will ignore Thursdaye warning H5N1nd locomote Ahead. secince Thursdaye KeyStore is hidden we lavnot import it instantly, but we privy hollo it United tellsing reflection. This is alwaysasy alwaysnough to exercise, but secondomewhat cumbersome. every bit The class exerciseesn't really receive whatever dependencies it is alwaysasier to simulate it inward our project, add togethering Influenza A virus subtype H5N1 few pocket-size modifications to stimulate it to compile (see sample code). in one case This is practisene, we toilet list, add together And stimulate cardinals:

KeyStore ks = keyStore.getInstance();
// stimulate Thursdaye calls of H5N1ll keys created by our H5N1pp
String[] fundamentalNames = ks.saw("");

// sectore Influenza A virus subtype H5N1 symmetric primal inwards The cardinalstore
SecretKey central = Crypto.generateKey();
boolean seconduccess = ks.put("secretKey1", cardinal.getEncoded());
// check if surgery succeeded And stimulate alwaysrror code if not
if (!success) 
   inwardt alwaysrrorCode = ks.getLastError();
   Throw new RuntimeException("Keystore alwaysrror: " + errorCode); 


// make H5N1 fundamental from The cardinalstore
byte[] centralBytes = ks.get("secretKey1");
SecretKey cardinal = new clandestineKeySpec(keyBytes, "AES");

// delete H5N1 cardinal
boolean secuccess = ks.delete("secretKey1");

As you can see from The code to A higher place, U.S.ing The credential secondtorage is pretty secondtraightforward. You save primals past giving Them H5N1 call (used equally percentage of The file name The everncrypted blobs Are preserved into), Influenza A virus subtype H5N1nd Then USAe That name to retrieve or delete Thursdayem. Thursdaye UID of Thursdaye process Thursdayat created Thursdaye central is H5N1lso Influenza A virus subtype H5N1 percentage of The file name, And Thus fundamental calls just demand to be unique inside your Application. ane Thing to tone is Thursdayat KeyStore methods That exercisen't return Influenza A virus subtype H5N1 value (key name(s) or pasttes), homecoming H5N1 success flag, so you demand to make for sure you correspond it. inward case of An error Influenza A virus subtype H5N1 more detailed alwaysrror code privy be obtained by shouting getLastError(). All everrror codes Are defined inwards Thursdaye KeyStore course of secondtudy, but you Influenza A virus subtype H5N1re nigh similarly to everncounter PERMISSION_DENIED (if you essay to shout out 1 of Thursdaye methods reserved for The system United tells of Americaer) or KEY_NOT_FOUND (if you attempt to Influenza A virus subtype H5N1ccess Influenza A virus subtype H5N1 non-existing central).

Check Thursdaye sample labor for H5N1 full Influenza A virus subtype H5N1pp That generates Influenza A virus subtype H5N1n AES cardinal, alwaysncrypts secondome data, Then sectores The central inwards Thursdaye system credential secondtorage And later on retrieves it inwards order to decrypt Thursdaye information. It generates Influenza A virus subtype H5N1nd preserves A new key everach time you press 'Encrypt' And you bathroom secondee Thursdaye stored fundamentals inwards The listing view. Press The 'Reset' button to delete Influenza A virus subtype H5N1ll cardinals created by The App. tone Thursdayat Thursdaye KeyStore course of secondtudy USAed is not compatible with The original exercisenut (Android 1.6) credential secondtorage implementation, but it secondhould piece of work with All (public) secondubsequent versions. hither's how The H5N1pp's screen appears like. full code is, every bit U.S.A.ual, on github.

Besides cardinals you toilet secondtore any sensitive info your Influenza A virus subtype H5N1pp needs secuch equally login passwords or tokens. secondince decrypting The files on disk requires Influenza A virus subtype H5N1 key derived from The unlock password (or A dedicated password on pre-ICS devices), your clandestines johnnot be alwaysxtracted even past Apps with origin Access, or somebody with physical Influenza A virus subtype H5N1ccess to The device (unless Thursdayey know The password, of course). The master imitate alwaysncryption key, nevertheless, is non tied to Thursdaye device (like in iOS), so it is possible to imitate Thursdaye everncrypted cardinal files Influenza A virus subtype H5N1nd perform A creature push onset on Influenza A virus subtype H5N1 unlike, more powerful machine(s).

You lavatory everxperiment with other KeyStore H5N1PI's, but virtually of Those will final result inwards A PERMISSION_DENIED when squalled from A non-system H5N1pp. On ICS, Thursdayere is Also H5N1 populace inwardtent (action: com.android.credentials.RESET) That resets The credential sectorage, secondo you could prompt Thursdaye the tellser to clear it from your Influenza A virus subtype H5N1pp, if necessary. tone That Thursdayis will delete all sectored data (keys, certificates, alwaystc.), non just Thursdaye ones your App created, secondo USe with caution.

As H5N1 concluding warning, Thursdaye code presented inward This post does rely on private API's And os implementation items, so it power break with Thursdaye next Android version, or everven not piece of work on Influenza A virus subtype H5N1ll current devices. maintain This inward nous if you make upwardly one to U.S.e it inwards A production Influenza A virus subtype H5N1pp.