Rotate Keys and Records

This guide shows how to rotate PureKit-related keys and update Pure Records. There can never be enough security, so you should rotate your sensitive data regularly (about once a week).

Also, use this flow in case your database has been COMPROMISED!

Use this workflow to get an update_token for updating user's Pure Record in your database and to get a new app_secret_key and service_public_key for your application.

Note! When a user just needs to change their password, use the EnrollAccount function (see the Password Encryption step) to replace the user's old record value in your DB with a new record.

Learn more about Pure Records and keys rotation as a part of Post-Compromise Security in this guide.

Get your update token

Navigate to your Application panel at Virgil Dashboard and, after pressing "BEGIN ROTATION PROCESS" press “SHOW UPDATE TOKEN” button to get the update_token.

Initialize PureKit with the update token

Move to PureKit configuration file and specify your update_token:

using Virgil.PureKit; // here set your PureKit credentials var context = ProtocolContext.Create( appToken: "AT.OSoPhirdopvijQlFPKdlSydN9BUrn5oEuDwf3Hqps", servicePublicKey: "PK.1.BFFiWkunWRuVMvJVybtCOZEReUui5V3NmwY21doyxoFlurSYEo1fwSW22mQ8ZPq9pUWVm1rvYhF294wstqu//a4=", appSecretKey: "SK.1.YEwMBsXkJ5E5Mb9VKD+pu+gRXOySZXWaRXvkFebRYOc=", updateToken: "UT.2.00000000+0000000000000000000008UfxXDUU2FGkMvKhIgqjxA+hsAtf17K5j11Cnf07jB6uVEvxMJT0lMGv00000=" ); var protocol = new Protocol(context);

Start migration

  • Run the update method of the RecordUpdater class to create a new user record
  • Save user's new record into your database.
using Virgil.PureKit; using Virgil.PureKit.Utils; var updater = new RecordUpdater("Update Token"); //for each record get old record from the database as a byte array //if you keep old record as a base64 string, get byte array from it: var oldRecord = Bytes.FromString(oldRecordBase64, StringEncoding.BASE64) //update old record var newRecord = updater.Update(oldRecord); //a WrongVersionException will be raised if "Update Token" has wrong version. //save new record to the database saveNewRecord(newRecord);

Note! You don't need to ask your users for a new password.

Note! The SDK is able to work with two versions of a user's record (old and new). This means, if a user logs into your system when you do the migration, the PureKit SDK will verify their password without any problems.

Download CLI

After you updated your database records, it's required to update (rotate) your application credentials. For security reasons, you need to use the Virgil CLI utility.

Download the preferred CLI package with one of the links below:

Rotate app secret key

Use Virgil CLI update-keys command and your update_token to update the app_secret_key and service_public_key:

virgil pure update-keys <service_public_key> <app_secret_key> <update_token>

Configure PureKit SDK with new credentials

Move to PureKit SDK configuration and replace your previous app_secret_key, service_public_key with a new one (same for the app_token). Delete update_token and previous app_secret_key, service_public_key.

using Virgil.PureKit; // here set up your PURE App credentials var context = ProtocolContext.Create( appToken: "New App Token", servicePublicKey: "New Service Public Key", appSecretKey: "New App Secret Key", ); var protocol = new Protocol(context);