Editing Virtual HSM

'''Virtual HSM (VHSM)''' is a software suite for storing and manipulating secret data outside the virtualized application environment. While [http://en.wikipedia.org/wiki/Hardware_security_module HSM] is a physical device connected to the computer, this software provides HSM functionality through the [http://www.emc.com/emc-plus/rsa-labs/standards-initiatives/pkcs-11-cryptographic-token-interface-standard.htm PKCS#11] API in virtual environment based on OpenVZ container technology.  

The architecture of the Virtual HSM is shown in the [[Media:Vhsm_overview.png|Fig. 1]]. The project consists of the following key components:

The VHSM VE contains the secure storage which is the database that stores the sensitive data in the encrypted form while other data (refer the table below) are stored unencrypted. The encryption key (master key) is derived from the user password using [http://en.wikipedia.org/wiki/PBKDF2 PBKDF2] and not stored in database. Utilizing PBKDF2 reduces the brute-force attack rate significantly if the database is compromised. The following table lists data that stored in the VHSM:

 

A client must be registered in the system to work with VHSM. VHSM admins (users with <tt>CKU_SO</tt> user type) can register new clients. These users can be both a real person or program. Anyway communication with the VHSM performed through the API. When the client is registered in the system a 256-bit authentication key is generated and encrypted in [http://en.wikipedia.org/wiki/Galois/Counter_Mode GCM mode] using the master key.  

The GCM mode guarantees integrity and confidentiality of the user data and therefore makes it possible to authenticate the encryption key derived from the user password. The VHSM uses this feature for user authentication. Registration process is shown in the [[Media:Vshm_user_registration.png|Fig. 3]].

 

A user is authenticated ([[Media:Vhsm_user_auth.png|Fig. 4]]) using the login/password pair and the container ID (VEID) where authentication request is received from. When a user is registered it's bound to the set of containers authorised to access VHSM API. If the user attempts to access to the VHSM from a non-authorized container the request is refused.

The data exchanging protocol between clients and the VHSM is written in the [https://code.google.com/p/protobuf/ Protocol Buffers] language. Inter-container communication is based on Netlink, so the OS kernel contains the module that passes messages between virtual environments while VEs contain the transport API library which interacts with this module via Netlink sockets.

The kernel module identifies containers by their VEIDs that are provided by OpenVZ. The VHSM environment ID is passed as a parameter to the module. Messages from other containers are routed to that VEID. The passed message contains serialized protobuf data and the header with the message type, container VEID and process PID (actually it's the unique socket ID generated by the kernel). Meaning of these parameters depends on the transfer direction. If the message comes from a client container then the module checks its VEID and forwards the message to the VHSM VE if the container is allowed to send requests to the VHSM. When the kernel module forwards the message it sets the VEID in the message header to the sender VEID and the PID to the sender process PID derived from the Netlink message header. So the VHSM can address the response to the client. If the message is transferred from the VHSM then the VEID and PID in the message header are set by the VHSM itself. It's possible because the VHSM sends responses to the client requests only and never initiates communication with a client.

The client part of the VHSM consists from the API-library and some auxiliary tools.

The VHSM API library partially implements [ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-11/v2-20/pkcs-11v2-20.pdf PKCS#11 v2.20 standard] and provides some additional functions for the user management.

Here the list of VHSM-specific features:

*: Currently only <tt>CKO_SECRET_KEY</tt> with key types <tt>CKK_GENERIC_SECRET, CKK_AES</tt> is supported

** encryption: <code>CKM_AES_CTR</code> (actually it's AES-GCM)

** <code>VHSM_GetUserSlot</code> returns slotID for the specified user

** <code>VHSM_ImportSecretKey</code> imports secret key with the default template

*: Following functions can be called only by <tt>CKU_SO</tt> user:

** <code>VHSM_CreateUser</code> creates a new VHSM user using the given template

** <code>VHSM_ModifyUser</code> allows to set user flags and VEIDs for the specified user

** <code>VHSM_DeleteUser</code> removes user and all associated data by user name

*: VHSM users have associated flags that determine which functions can be called by the user

** <tt>VF_CREATE_EXTENDED</tt> — user can create <tt>CKU_SO</tt> users. Only <tt>root</tt> user (created during VHSM installation) can has this flag

*: In the VHSM slots and tokens are abstract because users are authenticated by login/password pair. In fact, <code>C_GetSlotList</code> called from VE returns the list of usernames that can be used from this VE. Opening session with one of these slots means that in this session user wants to use username associated with this slot. [[Media:Vhsm_pkcs11_mapping.png|Fig. 5]] shows how it works.

*:Each thread must call <code>C_Initialize</code> to work with VHSM, as in PKCS#11, but if some thread logs into VHSM  then other threads with open VHSM sessions do '''not''' automatically log into VHSM as it should be according to the standard;

 

OpenSSL can act as a layer between a client application and the VHSM API library – it's achieved by OpenSSL [http://www.openssl.org/docs/crypto/engine.html engines] – and makes it possible to use a cryptographic device (or VHSM) without modifying the code of the client program. You may try pkcs#11 OpenSSL engines like [https://github.com/OpenSC/engine_pkcs11 engine_pkcs11], [http://sourceforge.net/projects/opencryptoki/files/PKCS%2311%20OpenSSL%20Engine/openssl-ibmpkcs11/ ibmpkcs11] with VHSM.

Install the following packages to build the project on your system. On CentOS use [http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F EPEL repositories]. In addition, VHSM uses some [http://gcc.gnu.org/ gcc]-specific features, so gcc 4+ is required.

* VHSM VE: <tt>vhsm</tt>

* Client VE: <tt>libvhsmapi.a, vhsm_admin</tt>

* Host: <tt>vhsm_transport.ko, vhsm_admin, vhsm_config</tt>

# Insert transport module: <code>insmod vhsm_transport.ko vhsm_veid=[veid]</code> where <code>[veid]</code> is VEID of the VHSM container. '''OR''' Use <tt>vhsm_config</tt> to configure VHSM

# Start VHSM in the VHSM container: <code>vhsm /path/to/storage</code>. You can init secure storage and create <tt>root</tt>-user on the first run

# Add VHSM users from host: <code>vhsm_admin user create <admin login> <admin password> [options...]</code>. Run <code>vhsm_admin help</code> for details.

# Now you can use VHSM from client VEs