XST Project/UserGuide/Encryption

XML Encryption Wizard

The XML Encryption Wizard consists of three pages, with a variable second page depending on the chosen keystore/ key option. To launch the wizard you either have to select an XML document in one of the supported views in the XML perspective or open an XML document in the WTP XML editor (in any perspective). Open the context menu, choose XML Security and click on New Encryption.... In order to encrypt a selected XML fragment select the desired document part in the editor and launch the wizard as described before. The selection has to exist before launching the wizard, and it has to be well-formed: in case a start-tag is selected the end-tag must be selected too. Encrypting only text-content of an element is possible too.

Resource and Encryption Type

This is the first page of the XML Encryption Wizard. You'll have to select the resource you want to encrypt, the encryption type, the keystore/ key option and the Basic Security Profile option.

Resource

It is possible to encrypt the complete document, the selected text or a document fragment specified by an XPath expression. The complete document is always possible. For a text selection this selection has to exist before launching the wizard and it has to be well-formed. XPath is always possible too. You can either enter an XPath expression in the textfield or you can select one in the dialog after clicking on the Browse... button. The XPath expression has to return exactly one element or element content. Encrypting attributes is not supported.

Encryption Type

The normal encryption type is a so called enveloping encryption, where the encrypted data is contained in the original document (it replaces the plain XML). A detached encryption doesn't encrypt the XML document you have chosen. Instead the data in the specified additional file here gets encrypted. Both documents will be changed. File A remains in plain XML, but does contain the encryption information for file B that gets encrypted (a detached encryption requires the whole document to be encrypted).

Keystore and Key

The chosen option here sets the following wizard page. You can either select to Use a Key from an existing Keystore, to Insert a new Key in an existing Keystore or to Create a new Key and a new Keystore.

Basic Security Profile

A Basic Security Profile compliant XML Encryption has some restrictions in comparison to a regular XML Encryption. By activating this checkbox all options in the XML Encryption Wizard will be limited to options that are compliant to this profile. In case of the XML Encryption Wizard this only limits the available algorithms on the Algorithms and Encryption Properties page.

Keystore and Key

The second page of the XML Encryption Wizard depends on your Keystore and Key selection on the first wizard page. You can select to Use a Key from an existing Keystore, Insert a new Key in an existing Keystore or to Create a new Key and a new Keystore.

Use a Key from an existing Keystore

Use a Key from an existing Keystore is one of the alternatives as the second wizard page. Simply select the keystore containing the key you want to use in the current encryption process. All data is verified, you can only switch to the next case with a correct keystore and key password as well as an existing key alias.

The wizard automaticall stores the entered data for the keystore name and the key name between sessions. Passwords are never stored and have to be entered every time.

Insert a new Key in an existing Keystore

Insert a new Key in an existing Keystore is one of the alternatives as the second wizard page. Select an existing keystore (probably one you created before with the help of the Create a new Key and a new Keystore wizard) and enter the keystore password. After that simply select the desired algorithm and the algorithm size for the new key and enter a name and a password for it. Click the Generate button when you are done to create the new key. A short message informs you about the generation result and the Next button will be enabled. The key generated here will be used in the active encryption process.

Keys must be unique inside a keystore, so the wizard verifies that the entered key name does not exist in the selected keystore.

The wizard automatically stores the entered data for the keystore path and name between sessions. Passwords are never stored and have to be entered every time.

Create a new Key and a new Keystore

Create a new Key and a new Keystore is one of the alternatives as the second wizard page. This page lets you create a new keystore together with a new key. Enter the name for the keystore and the password to protect it. After that choose an algorithm and its size and enter an alias name together with a password for the key. The keystore password is used to protect the whole keystore, the key password to protect the key. Both passwords are required.

Click the Generate button when you are done to create the new keystore together with the key. A short message informs you about the generation result and the Next button will be enabled. The keystore is stored with the entered name in the active folder (normally the active project). The key generated here will be used in the active encryption process.

Algorithms and Encryption Properties

This is the last page of the XML Encryption Wizard. You must select the Encryption and the Key Wrap Algorithms. Optional, you can select to keep the root element as plain text and you can enter an encryption ID (strongly recommended). The Start Signature Wizard afterwards checkbox enables you to start the signature wizard after successfully encrypting the selected XML document.

Encryption and Key Wrap Algorithm

Choose the algorithms you want to use to encrypt the XML document (fragment) and to wrap the key. You have to select algorithms that do match with the selected key on the previous wizard page.

Properties

There is only one property available: Keep root element as plain text. This creates an encrypted XML document (fragment) with a root element in plain text. In case you selected to encrypt the whole document the documents root element will be kept as plain text. In case you selected to encrypt a document fragment only (via a text selection or an XPath expression) this will result in a plain text root element of this document fragment.

Encryption ID

The encryption ID is optional, but it is strongly required to enter one. This ID must be unique in the whole document and may not contain <, >, &, ' or " characters. Without an encryption ID it is only possible to decrypt the XML document step by step.

Signature Wizard

Select the checkbox in case you want to start the XML Signature Wizard directly after the encryption process was successfully finished.