Vault Installation

The concepts of files and vaults are briefly described here.

Database Vaults

Database vaults do not have to be "installed". By creating a database vault using any administration GUI (e.g. ice.NET Studio), everything is complete. The vault can be used without further action.

File Vaults

In order to use File vaults, two configurations must be present:

  • The database vault entry, to be created the same way as a Database vault, just the Vault Type should be set to FileVault
  • Additional configuration, either stored in the database together with the vault entry or in the application .config file

To store the additional configuration in the database, use a configuration GUI of your choice, e.g. the ice.NET Studio Administration User Interface. Click on the File Vault in the Administration/Vaults tab, select the appropriate configuration type ("protocol") and insert the configuration values:

The specific configuration values will be described later, together with their configuration types.

Alternatively, the additional configuration can be inserted into the application .config XML file. For each vault a configuration/ice.net/vaults/vault element is required: 

<configuration>
    [...]                
    <ice.net>
        <database service="SQLServer" connectionString="server=(local)\SQLEXPRESS;trusted_connection=yes;database=test_ice;connect timeout=120" encrypted="false"/>
        <license path="..\..\license.xml"/>
        <vaults>
            <vault name="Simple" basePath="..\..\__vault"/>
            <vault name="IceVault" protocolFactory="PDTec.IceNet.Domain.VaultServer.IceNetVaultProtocolFactory,PDTec.IceNet.Domain">
                <parameter name="BaseUrl" value="http://www.corp.com/icevault/icevault.ashx" />
                <parameter name="BaseClientUrl" value="http://www.corp.com/icevault/icevault.ashx" />
                <parameter name="AuthorizationMethod" value="RSA" />
                <parameter name="PrivateKey" file="..\..\IceFileTransfer_AppServer.rsa" encrypted="false" />
                <parameter name="MaxRequestSize" value="1024" />
            </vault>
        </vaults>
        [...]
    </ice.net>        
</configuration>

Simple File Vault

Simple File Vaults require a filesystem storage area (fileshare) that is accessible from the application server. The path to this fileshare must be provided in the vault configuration.

The only configuration setting that has to be entered is the basePath:

The equivalent .config entry is similarly simple: 

<vault name="Simple" basePath="\\server\share\__vault01" />

IceVault

IceVaults enable the separation between Application Server and Vault Server. Therefore the application server does not directly access the vault fileshare but communicates with the vault server. Both servers must be configured:

IceVault - Application Server Configuration

For the Application Server the following parameters are relevant:

Parameter Values Description
ProtocolFactory PDTec.IceNet.Domain.VaultServer. IceNetVaultProtocolFactory, PDTec.IceNet.Domain The class name of the protocol implementation factory. This value is fixed for IceVaults.
BaseUrl HTTP/S URL The URL of the Vault Service that is accessible from the Application Server.
BaseClientUrl HTTP/S URL The URL of the Vault Service that is accessible from the Client site. This parameter is optional and defaults to BaseUrl. In enviromnents with firewalls and intranet/internet zones this is required to enable Smart Client access.
AuthorizationMethod RSA The cryptographic method used to sign and verify vault service commands. The value should be RSA for maximum security.
PrivateKey File reference or binary content stored in DB. The private RSA key used to sign vault service commands. This key must be kept secret. It is not necessary to distribute the private key to the vault servers. The public RSA key generated from the private key is sufficient (and not secret).
MaxRequestSize [kB] HTTP servers have a maximum request size limit. With this parameter the maximum size of a HTTP request that is sent to the vault server is specified. The default setting of 1024 kB should be a good tradeoff between speed and reliability.

The settings can be applied in the ice.NET Studio (switch to IceVault protocol):

The private RSA key can be either uploaded or generated by the application server. Once the private key is in the database, a derived public key file can be downloaded. This public key file must be accessible from the vault server to verify URLs generated by the application server. If the private key is regenerated, all derived public keys become invalid.

The equivalent .config entry looks like this (here the public RSA key must be stored in a file): 

<vault name="IceVault" protocolFactory="PDTec.IceNet.Domain.VaultServer.IceNetVaultProtocolFactory,PDTec.IceNet.Domain">
    <parameter name="BaseUrl"               value="http://www.corp.com/icevault/icevault.ashx" />
    <parameter name="BaseClientUrl"         value="http://www.corp.com/icevault/icevault.ashx" />
    <parameter name="AuthorizationMethod"   value="RSA" />
    <parameter name="PrivateKey"            file="..\..\IceFileTransfer_AppServer.rsa" encrypted="false" />
    <parameter name="MaxRequestSize"        value="1024" />
</vault>

IceVault - Vault Server Configuration

For the Vault Server the following parameters are relevant:

Parameter Values Description
name Vault Name The vault name identifies the vault. A vault service can handle multiple vaults.
basePath Fileshare path The root directory used by the vault service to store binary files. The vault service creates directories and files under this root path. Therefore full access permissions must be granted to this directory and all subdirectories to the vault service worker process user (e.g. BUILTIN\IIS_IUSRS).
authorizationMethod RSA The cryptographic method used to sign and verify vault service commands. The value should be RSA for maximum security.
publicKeyFile File reference. The public RSA key used to verify vault service commands. The public RSA key generated must be generated from the appropriate private key on the application server.

The settings must be stored in the web.config of the vault service under configuration/ice.net/components/vault.server/vaults/vault: 

<configuration>
    [...]                
    <ice.net>   
        [...]       
        <components>
            <vault.server>        
                <vaults>        
                    <vault name="IceVault" basePath="..\__vault" authorizationMethod="RSA" publicKeyFile="..\IceVault_VaultServer.rsapub" />    
                </vaults>
            </vault.server>
        </components>
    </ice.net>        
</configuration>