Sample Secret Key Picker control markup

Here is some sample markup generated by the Secret Key Picker control helper:

<xp:div>
	<xp:label value="Encrypt Document"
		style="padding:10px" for="inputText1" id="label1">
	</xp:label>
	
	<xp:inputText id="inputText1" 
		multipleSeparator=", "
		multipleTrim="true"
		readonly="#{javascript: !document1.isEditable();}"
		value="#{viewScope.secretKeysForDocument1}"
		style="margin:10px">
		<xp:this.defaultValue><![CDATA[#{javascript: return document1.getEncryptionKeys();}]]></xp:this.defaultValue>
	</xp:inputText>
	
	<xe:secretKeyPicker for="inputText1" id="secretKeyPicker1">
	
		<xe:this.dataProvider>
			<xe:simpleSecretKeyPicker>
				<xe:this.secretKeyList><![CDATA[#{javascript:
				// Your SSJS code to populate the keys goes here 
				//@UserSecretKeys();}]]>
				</xe:this.secretKeyList>
			</xe:simpleSecretKeyPicker>
		</xe:this.dataProvider>
	</xe:secretKeyPicker>
	
	<xp:messages id="encryptionMessagesForDocument1"></xp:messages>
</xp:div>

Four controls are generated in total in the Secret Key Picker section of the markup, Note also that some properties on the targeted Domino® document data source are also updated. Those updates are shown in the snippet below with the relevant affected properties highlighted in bold font.

<xp:this.data>
	<xp:dominoDocument var="document1" 
		formName="todo" 
		computeWithForm="both" 
		encryptionKeysProvider="#{viewScope.secretKeysForDocument1}">
	</xp:dominoDocument>
</xp:this.data>

Continuing to explain the generated markup, the purpose of the label and messages tags is self-evident. The purpose of the inputText field is to hold the keys selected by the Secret Key Picker control.

As the control can contain multiple keys, it is configured to separate entries using commas and to remove any leading or trailing spaces. If the document is not editable, which would occur, for example, if the user does not possess any of the keys used to encrypt the doc, then this field is set to read-only.

Most importantly, it binds its own value to a view scope variable called, in this instance, secretKeysForDocument1. Once the user selects keys from the key picker, they are displayed in the inputText control and also stored in a view scope variable. That same view scope variable is attached to the document data source (see the bold markup text) which is responsible for saving and encrypting the document. The reference to the view scope variable is what enables the data source to retrieve the secret keys and perform the encryption operation when the document is being updated. This linkage is key for successful encryption

secretKeyPicker control usage further explained

Finally, in the markup, there is the secretKeyPicker tag itself. Like other XPages picker controls (for example, the Name Picker and Value Picker), the Secret Key Picker is linked to a text control identified by the id specified in the for property. Also, the Secret Key Picker has a data provider whose function is to populate the contents of the picker control.

The data provider can be anything that returns one or more keys. Examples would be a static string of comma separated entries, such as "key1, key2, key" or a computed function like an @DbLookup() or@UserSecretKeys(). @UserSecretKeys()is included in the code generated by the helper dialog as a hint as to what action the developer should take (that is, the function call itself is commented out).

@UserSecretKeys() is provided as a convenience function to extract keys from a user's ID file. There is also a UserID class available in Java™ and LotusScript® which provides a getEncryptionKeys() method that fulfills the same function. The function in its simplest form (that is, with no parameters provided) uses the current user name and password to query the ID Vault and return an array of any secret keys found in the user ID. The ID Vault is assumed to be on the current Domino® server by default, but all of these parameter values can be explicitly passed to the function if the default options are not applicable. More information on the @UserSecretKeys() function is provided in the topic provided in the Domino® Designer Basic User Guide.

When a user creates an XPage and uses the Secret Key Picker control to select encryption keys, then saving the document will automatically encrypt any encryptable fields that are bound to the Domino® document data source. Any user reading the document will only see the content of the encrypted fields if they have one or more of the secret keys used to encrypt the document. If the user does not possess the required keys then the encrypted field content will not be displayed and the messages control will display the following message:

You cannot access portions of this document because it was encrypted and you do not have any of the keys