{"id":21835,"date":"2015-10-19T11:21:27","date_gmt":"2015-10-19T18:21:27","guid":{"rendered":"https:\/\/blog.xamarin.com\/?p=21835"},"modified":"2015-10-19T11:21:27","modified_gmt":"2015-10-19T18:21:27","slug":"easily-authenticate-users-with-androids-confirm-credential","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/xamarin\/easily-authenticate-users-with-androids-confirm-credential\/","title":{"rendered":"Easily Authenticate Users with Android’s Confirm Credential"},"content":{"rendered":"

\t\t\t\tThere are a number of ways to authenticate users on mobile devices, from traditional passwords and pins to new biometric fingerprint sensors. Most users are already using one of the most secure mobile authentication implementations, the device lock screen. With Android Marshmallow and the new Confirm Credential API, it’s now possible to utilize the lock screen to detect when the user last unlocked their device and even re-prompt them to confirm their identity without having to remember yet another app-specific password. All authentication is securely stored in a crypto key from the Android KeyStore with a customizable timeout period that’s carried across multiple applications.<\/p>\n

\"confirm-980x576\"<\/p>\n

Getting Started<\/h2>\n

It’s important to note that your user must have his or her lock screen already secured in Android’s settings before it’s possible to use the Confirm Credential API. Most Android users will have already done this, but it’s possible to check before even attempting by getting access to the KeyguardManager and prompting users to secure their lock screen:<\/p>\n

\n\/\/Create private KeyguardManager that will be used later on for Confirm Credentials\nKeyguardManager keyguardManager;\n\nprotected override void OnCreate(Bundle bundle)\n{\n  \/\/...Activity creation\n  keyguardManager = (KeyguardManager)GetSystemService(Context.KeyguardService);\n  if (!keyguardManager.IsKeyguardSecure)\n  {\n    \/\/ Show a message that the user hasn't set up a lock screen.\n    Toast.MakeText(this, \"Secure lock screen isn't set up.\\n\"\n                    + \"Go to 'Settings -> Security -> Screen lock' to set up a lock screen\",\n                    ToastLength.Short).Show();\n  }\n  else\n  {\n    \/\/We are free to create our Cyrpto Key\n    CreateKey();\n  }\n}\n<\/pre>\n
Creating Crypto Key<\/h2>\n
Once it’s verified that the user has set up a secure lock screen, it’s possible to attempt to create a crypto key with a specified timeout policy that’s used to see when the user last logged in. This timeout is set for a number of seconds, and developers are free to set it to any amount necessary for the app.<\/p>\n
\nconst string KeyName = \"my_special_key\";\nvoid CreateKey()\n{\n  \/\/ Generate a key to decrypt payment credentials, tokens, etc.\n  \/\/ This will most likely be a registration step for the user when they are setting up your app.\n  var keyStore = KeyStore.GetInstance(\"AndroidKeyStore\");\n  keyStore.Load(null);\n  var keyGenerator = KeyGenerator.GetInstance(KeyProperties.KeyAlgorithmAes, \"AndroidKeyStore\");\n\n  \/\/ Set the alias of the entry in Android KeyStore where the key will appear\n  \/\/ and the constrains (purposes) in the constructor of the Builder\n  keyGenerator.Init(new KeyGenParameterSpec.Builder(KeyName, KeyStorePurpose.Decrypt | KeyStorePurpose.Encrypt)\n\t\t\t\t\t   .SetBlockModes(KeyProperties.BlockModeCbc)\n\t\t\t\t\t   .SetUserAuthenticationRequired(true)\n                                           \/\/ Require that the user has unlocked in the last 30 seconds\n\t\t\t\t\t   .SetUserAuthenticationValidityDurationSeconds(30)\n\t\t\t\t\t   .SetEncryptionPaddings(KeyProperties.EncryptionPaddingPkcs7)\n\t\t\t\t\t   .Build());\n  keyGenerator.GenerateKey();\n}\n<\/pre>\n
Testing Last Unlock<\/h2>\n
When your code needs to authenticate the user, it simply needs to attempt to encrypt any data with the key that was created earlier. If the data can be encrypted with the key, then the user has logged in within our timeout period. If not, an UserNotAuthenticatedException<\/i> is thrown and it’s time to confirm credentials. Here’s how to test encrypting a bit of data.<\/p>\n
\nstatic readonly byte[] SecretData = new byte[] { 1, 2, 3, 4, 5, 6 };\nvoid TryEncrypt()\n{\n  try\n  {\n    var keyStore = KeyStore.GetInstance(\"AndroidKeyStore\");\n    keyStore.Load(null);\n    var secretKey = keyStore.GetKey(KeyName, null);\n    var cipher = Cipher.GetInstance(KeyProperties.KeyAlgorithmAes + \"\/\" + KeyProperties.BlockModeCbc + \"\/\"  + KeyProperties.EncryptionPaddingPkcs7);\n    cipher.Init(CipherMode.EncryptMode, secretKey);\n    \/\/attempt encrypting data\n    cipher.DoFinal(SecretData);\n    \/\/ If the user has recently authenticated, you will reach here.\n  }\n  catch (UserNotAuthenticatedException)\n  {\n    \/\/ User is not authenticated, let's authenticate with device credentials.\n    ShowAuthenticationScreen();\n  }\n}\n<\/pre>\n
Showing the Authentication Screen<\/h2>\n
If the user is already authenticated, the app can move on to a checkout screen or log the user in. Otherwise, it’s time to prompt the user to confirm their credentials by simply creating a new Confirm Device Credential Intent from the KeyguardManager.  <\/p>\n
\nstatic readonly int ConfirmRequestId = 1;\nvoid ShowAuthenticationScreen()\n{\n  var intent = keyguardManager.CreateConfirmDeviceCredentialIntent((string)null, (string)null);\n  if (intent != null)\n  {\n    StartActivityForResult(intent, ConfirmRequestId);\n  }\n}\n<\/pre>\n
Android will automatically launch the lock screen that the user has specified when the Confirm Credential Intent is activated, whether it be a pin, password, or any other type of security such as a fingerprint. Personally I use a pin on my devices, so here’s what it looks like on my Nexus 9 when the intent is launched:<\/p>\n
\"Pin<\/p>\n
At this point the user can do one of two things: <\/p>\n