This article introduces you to Version Chain Policy and by way of example shows you how it affects operation.
Introduction
The previous Walkthrough, :Recover w/ Shared Content, combined a number of SSProtect concepts together, defining basic terms while carrying out common operations. This included reference to a Version Chain, a progressive collection of Version Instances that share a single 16-byte FileID representing ordered revisions to a Managed Item.
Version Chain Policy allows you to configure the way Version Chains are managed when copying, moving, and/ or renaming Managed Content before applying additional changes. This Walkthrough guides you through basic operations using different Version Chain Policy settings to show the options available to Account holders.
Prerequisites
This Walkthrough is best reviewed in ordered fashion as described in the article, Overview and Terms. Version Chain Policy is an advanced topic that requires a solid understanding of underlying SSProtect principles. To ensure readiness for the material that follows, make certain you understand details in the Walkthrough, :Recover w/ Shared Content: If its' proceedings are not clear, it will be nearly impossible to take advantage of the value offered by the different Version Chain Policy settings.
Split vChain Overview
When you first Protect a data item, for example a file, SSProtect creates a unique 16-byte FileID and the Version Instance v1, assigning both to the file. The FileID is stored as a part of the encrypted content's header, while the Version is only available through KODiAC Cloud Services interpretation of additional header details.
Subsequent access to the same item results in a newly encrypted Version 2, the next unused revision number for the input material's FileID. What happens when you Copy the v2 instance and subsequently modify its' content?
Because the copy carries the FileID, subsequent access (and resulting re-encryption) retains the same FileID and bumps the Version number to the next available, v3. Now let's look at what happens when we modify both the original and the copy:
The first operation creates v4, the subsequent creates v5, and so on: Each successive operation is assigned the next-available unused Version number specific to the FileID. In the noted case, we show original_file.txt first modified, so it acquires v4 while subsequent modification to copied_file.txt gets assigned v5.
Suppose you wanted the Copy to be its' own instance, effectively, "splitting" the data and starting over at Version 1? You can do this by enabling Split vChains. The procedure, above, with Split vChains, becomes:
This may seem confusing at first glace, however note that SSProtect does not make adjustments to content until it's accessed and stored. As such, the original Version Instance of copied_file.txt is the same as the v2 instance of original_file.txt: The FileID - and information - doesn't change on the Copy operation, it's detected on first subequent access and applied on the next re-encryption when Split vChains Policy is set. In this case, re-encryption creates a new FileID and starts at Version 1. In our example, this is triggered because the filename has changed (though only if the Data Owner carries out the operation).
Though the diagram shows two instances of v2 - copied_file.txt, the top-right and bottom-right, they have different FileIDs and represent the two different, independent Version Chains.
Split vChain Triggers
Version Chains are Split whether source material is Copied or Moved: The Split operation is specific to:
- A Data Owner modifying a Managed Item that carries a different filename, independent from any change to its' path
- Optionally, a Data Owner modifying a Managed Item that has, "moved" in that its' path has changed, even if its' filename has not
The second, optional setting, Move Splits in the License and Components Interface, is further described in the article, Version Chain Policy.
IMPORTANT: Move Splits refers to a change of path, not a technical filesystem Move vs. Copy operation - both trigger the condition.
Default Operation: No Split vChains
Let's work through the sample progression from above.
STEP 1: Refresh Login and choose the Profile matching Org1_Admin to Log In.
STEP 2: Create a text file, C:\TestData\original_file.txt and add the content, v1 - Test Data. Save/ Close.
STEP 3: From File Explorer, right-click C:\TestData\original_file.txt then choose SSProtect Activate. You should see the Red SSProtect Explorer Overlay icon for the target file.
STEP 4: From the SSProtect notification icon's context menu, choose Managed Files/ Restore and from the list, select original_file.txt then click Versions.... We will leave this open for the next few operations:
STEP 5: Return to File Explorer and make a copy of the file you just protected: Select the file, press ctrl-c together, then follow with ctrl-v together: This creates the file original_file - Copy.txt. Right-click this file, choose Rename, and name the file copied_file.txt:
STEP 6: Double-click copied_file.txt to perform a Managed Access operation, enter the line, v2 - Copied Data, then Save/ Close. Wait for the file to present with the Red Overlay Icon indicating that it's been SSProtect'd.
STEP 7: Return to the SSProtect Versionlist pane and click Refresh: You will now see two Versions:
Notice, at the top, we're still viewing Versions of the original file, C:\TestData\original_file.txt; though we've made a Copy and modified it, we're still effectively working with the original Version Chain.
STEP 8: Click Host List... then Refresh to see the two managed Hostlist instances:
STEP 9: Make sure you've selected copied_file.txt then choose Versions...: The two enumerated Versions are the same as those shown for original_file.txt, above.
Remember that original_file.txt is Version 1 of the Version Chain, which we copied to copied_file.txt. Once we modified copied_file.txt, SSProtect created Version 2 of the same Version Chain (with matching FileID). As a result, we end up with file instances for both v1 and v2 in File Explorer.
STEP 10: From the Versionlist for copied_file.txt (current view from STEP 9), select both instances then Restore.
STEP 11: Click Host List... then choose original_file.txt, then Versions.... Select both instances then Restore.
STEP 12: From File Explorer, choose all four Restored instances then shift-right-click and choose SSProtect Release. Select all four files then press [Enter] on your keyboard to open them. Compare results: The -v1 instances will contain the 1st line, v1 - Test Data and the -v2 instances will contain both the noted v1 line and also, v2 - Copied Data.
This is suitable default behavior for certain work habits. Let's take a look at what Split vChains offers.
Configure Split vChains
Let's repeat the previous progression with Split vChains.
STEP 13: Dismiss the Versionlist dialog, then from the notification icon's context menu, choose License and Components:
STEP 14: At the bottom, just to the right of center, check Split vChains. Confirm the prompt by choosing Yes. SSProtect will end your Login Session and display the Login dialog. Log In with your Password to proceed.
IMPORTANT: This step enables Split vChains for your Organization but does not configure it for any existing member Account.
For detailed information regarding Version Chain configuration and trigger conditions, refer to the article, Version Chain Policy.
STEP 15: Enable Split vChains for your Account by navigating through Administer Users/ Manage from the notification icon's context menu. Select your Account from the Userlist,* for us definisec+test1@gmail.com, then click Edit. Find and check Split vChain which is slightly below and to the right of the dialog's center. Click Save then OK to dismiss the dialog.
* Note that the Userlist, "P" column (Privilege) displays the, "*" designation to help you find your own entry in the list. Since you're using the Administrator Account, the Privilege column for your Account also includes, "A" for (Administrator), thus, "A*".
View the Impact of Split vChains
Let's repeat the previous progression now that we have enabled Split vChains.
STEP 16: Create a new text file, C:\TestData\original_split.txt, and enter, v1 - Test Data. Save/ Close.
STEP 17: Right-click original_split.txt in File Explorer, then choose SSProtect Activate.
STEP 18: As in the previous progression, navigate to Managed Files/ Restore and in the Hostlist, choose original_split.txt and click Versions... to display the one instance of the file we just created.
STEP 19: Return to File Explorer and copy original_split.txt to copied_split.txt.
STEP 20: Double-click copied_split.txt and enter the line, v1 - SPLIT DATA. Save/ Close, then wait for the Red Overlay Icon to present itself.
STEP 21: Return to the SSProtect Versionlist pane and click Refresh:
Unlike before, we only see one Version Instance for C:\TestData\original_split.txt, shown at the top left. This is because SSProtect, during Managed Close, recognizes that the target filename is different and, as a result of the Split vChain Policy, creates a new FileID and Version Instance=1 for the copied_split.txt file. This doesn't impact original_split.txt because it's a different FileID: The Version Chain has been Split.
STEP 22: Click Host List... then Refresh, choose the file copied_split.txt and click Versions...:
As expected, we see the new, "split" Version Instance=1 for copied_file.txt - an independently-managed item.
Managed Files and Version Chains
Overall, we have, with the STEP guidance above, created three independent Version Chains from four files:
- Version Chain/ FileID ~ 1, Version Instance = 1, C:\TestData\original_file.txt
- Version Chain/ FileID ~ 1, Version Instance = 2, C:\TestData\copied_file.txt
- Version Chain/ FileID ~ 2, Version Instance = 1, C:\TestData\original_split.txt
- Version Chain/ FileID ~ 3, Version Instance = 1, C:\TestData\copied_split.txt
Remember from the first sequence (without Split vChains) that both original_file.txt and copied_file.txt resolve to the same two Version Instances in the Versionlist - as expected by the matching FileIDs in the list above. Let's compare the resulting Hostlist and the Archivelist for all files.
STEP 23: Continuing from the previous STEP's context, choose Host List... to display Managed Files (Hostlist):
Notice we see all four files: The Hostlist enumerates actively-managed content for the Login Session's Account. Let's take a look at the KODiAC Managed Data Archive:
STEP 24: Choose Archive... to display the Archivelist:
The Archivelist shows three of the four files we've been working with - representing the three Version Chains we created with our activities. The Archivelist list as a result doesn't show original_file.txt specifically because it's an older Version Instance of the Version Chain represented by v2 of copied_file.txt.
Display the Latest Version
The Archivelist displays the latest Version of each Managed Item available for Restore from the KODiAC Managed Data Archive - for the Login Session's Account. If, from the latest state shown above, we were to access original_file.txt then Refresh the Archivelist, the v2 instance of copied_file.txt would be replaced with the v3 instance of original_file.txt.
STEP 25: From File Explorer, double-click C:\TestData\original_file.txt then add a couple lines, v2 - <other> then, v3 - Latest Data and Save/ Close. Return to the Archivelist and Refresh (after the Red Overlay Icon presents in File Explorer):
As expected, we see the latest instance for the associated Version Chain: v3 of original_file.txt.
Looking Deeper: Latest Qualified Versions
The scenarios we presented in this Walkthrough are relatively simple since most real-world content is shared with Organization Peers and/ or Third Party Trusts. What, then, if the latest Version Instance had been created by a Sharing Peer? In some cases, shared content cannot be Restored even by the Data Owner. Specifics are described in the Walkthrough, :Recover w/ Shared Content and also described in the article, Managing Archive Data.
In general, the Archivelist displays the Latest Qualified Version for Restore, as follows:
When SSProtect enumerates Archivelist details, for each Version Chain it starts with the most-recent Version Instance and checks Restore Availability for the calling context, i.e. your Account. If the Version Instance is not available for Restore, for any reason,* SSProtect moves to the previous Version Instance and checks again, working all the way back to v1. When the Version Chain doesn't offer up a Version Instance for Restore, the Version Chain's instance isn't displayed in the list. Else, the resulting Version Instance is the Latest Qualified Version (as more than one Version Instance may be available for Restore).
The Hostlist, similarly, presents details specific to the Latest Qualified Version - though the format differs, the instance is the same as that in the Archivelist. In fact, Restore operation, for a Managed File, from either the Hostlist or the Archivelist, yields the same result - the Latest Qualified Version. This is also the highest-numbered Version displayed in the Versionlist as Available for Restore (a, "Y" in the right-most, "A" column of the Versionlist).
* Did You Know: If a Sharing Peer executes a Managed Close operation (automatically resulting from In-Place Encryption or from a Release/ Activate combination that tracks the Version Chain) and the File's plaintext size exceeds the Data Owner's available :Recover Quota, SSProtect and KODiAC will, "fall back" to Optimized Offloading to ensure data is protected. At the same time, KODiAC delivers one single Quota warning notification via email, further suppressed until the Account's Quota is adjusted (at which point any future recurrence delivers a new warning).
For more information on :Recover Quotas, refer to the article, Archives, Quota, and Retention Policy. For details regarding delivery of warning Notifications, refer to the article, Email Notifications.
Exclusive Hostlist
If we return to the Hostlist shown in STEP 23, we can click Excl vChains to display only the latest instance of any given Version Chain. This would have the effect of suppressing original_file.txt from the associated screenshot, though if we do this after STEP 25, original_file.txt would be present and copied_file.txt would not.
Note that this setting operates as a display filter, which you can toggle on/ off to dynamically switch between renderings: Excl vChains does not affect permanent changes to Managed Content or its' enumeration.
Version Chains and Sharing Peers
Version Chain Policy is only assessed when content is re-encrypted by the Data Owner: Sharing Peer activity never triggers a vChain Split operation based on Policy (though the chain may, "break" (Split) as noted below).
The reasons for this may be somewhat obvious: When sharing data with a peer, content is most often moved from one physical computer to another, which means the next access operation by the Sharing Peer is likely performed in a file path mapping that differs from the Data Owner's v1 location. The Sharing Peer may also name the file differently (and in our experience the probability of a Sharing Peer renaming the file is directly proportional to the probability that the Sharing Peer is a lawyer).
Note, however, that upon return to the Data Owner, if modified content is saved to a location other than the original v1 instance and vChain Policy is enabled with Move Splits also asserted, the Version Chain will be Split on subsequent re-encrypt operation. For this reason, we advise caution in using Move Splits.
Impact of Release/ Re-Protect On Version Chains
IMPORTANT: A Sharing Peer - whether an Organization Peer or Third Party Trust - will, as noted, never execute a Split vChain operation and furthermore always attempts to maintain Version Chain integrity. So long as you do not change the name and location of a managed file between decrypt and re-encrypt (for example with SSProtect Release then subsequent SSProtect Activate), SSProtect will maintain the Data Owner, Version Chain, and proper Version Instance assignment for re-encrypted content.
In general, you can rename and/ or relocate a Managed Item then perform SSProtect Release and maintain the Version Chain even if you then Refresh Login and/ or make changes to the file: So long as you SSProtect Activate the same filename and filepath on which you performed Release, SSProtect should maintain Version Chain Policy, based on the context of the caller.
NOTE: If you perform a Hostlist Clean operation between Release and Activate:
- For a Data Owner, this breaks (Splits) the Version Chain in every case
- For a Sharing Peer, this breaks (Splits) the Version Chain only if you you choose to Clean the Shared List (an option asserted by a prompt after you initiate Clean). For more information, refer to the article, Managing Host Data.
Additional Resources
You can search this site for more information on various topics, or use this link to submit a specific request. You can also send email directly to support@definisec.com, and our staff will respond to your needs as soon as possible.
In the meantime, don't forget to check out our primary website and Insights columns for information on current trends, security topics, and how our technologies relate.
This article was updated w/ v10.7.1 of the :Foundation Client