Difference between revisions of "Virtual HSM"

From OpenVZ Virtuozzo Containers Wiki
Jump to: navigation, search
Line 1: Line 1:
−
'''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 in virtual environment based on OpenVZ container technology.  
+
'''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.  
  
 
== Structure ==
 
== Structure ==
−
The project consists of the following key components:
+
[[File:Vhsm_overview.png|thumb|right|400px|Fig. 1 — VHSM overview]]
 +
The architecture of the Virtual HSM is shown in the [[Media:Vhsm_overview.png|Fig. 1]]. The project consists of the following key components:
 
;VHSM virtual environment
 
;VHSM virtual environment
 
:VHSM VE is the isolated environment that contains the VHSM server and secure storage. The server performs operations on secret data and storage keeps encrypted user data
 
:VHSM VE is the isolated environment that contains the VHSM server and secure storage. The server performs operations on secret data and storage keeps encrypted user data
Line 12: Line 13:
 
== Details ==
 
== Details ==
 
=== VHSM virtual environment ===
 
=== VHSM virtual environment ===
−
The VHSM VE contains the secure storage which is the database that stores the sensitive data in the encrypted form while other data (import date, purpose, etc) are stored unencrypted. The encryption key (master key) is generated from the user password using [http://en.wikipedia.org/wiki/PBKDF2 PBKDF2], and the salt that is used in the function is stored unencrypted in database. Thereby the VHSM doesn't keep the encryption key and utilizing PBKDF2 reduces the brute-force attack rate significantly if the database is compromised.
+
[[File:VHSM_data_encryption.png|thumb|right|400px|Fig. 2 — Data encryption in the VHSM]]
 +
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 generated 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:
 +
{|class="standard" border="1"
 +
!Data
 +
!Type
 +
!Encrypted
 +
!Comments
 +
|-
 +
|Key ID
 +
|string
 +
|no
 +
|keys in the VHSM can be accessed by their string-ID
 +
|-
 +
|Key data
 +
|blob
 +
|yes
 +
|encrypted key data (see the [[Media:VHSM_data_encryption.png|Fig. 2]])
 +
|-
 +
|Key attributes
 +
|blob
 +
|no
 +
|data structure that holds PKCS#11 key attributes
 +
|-
 +
|Import date
 +
|date-time
 +
|no
 +
|key creation date
 +
|-
 +
|User name
 +
|string
 +
|no
 +
|VHSM user login
 +
|-
 +
|User auth key
 +
|blob
 +
|no
 +
|binary data for the user password check
 +
|-
 +
|User type
 +
|integer
 +
|no
 +
|<tt>CKU_USER</tt> or <tt>CKU_SO</tt> from the PKCS#11 standard
 +
|-
 +
|User flags
 +
|integer
 +
|no
 +
|Flags determine access rights (read, write, delete) for the user
 +
|-
 +
|Password derivation params
 +
|integer
 +
|no
 +
|PBKDF2 params used for master key derivation (refer the Fig. 3)
 +
|-
 +
|User VEIDs
 +
|integer
 +
|no
 +
|List of VEIDs where the user can get access to the VHSM
 +
|}
 +
 
 +
[[File:Vshm_user_registration.png|thumb|right|400px|Fig. 3 — User registration]]
 +
[[File:Vhsm_user_auth.png|thumb|right|400px|Fig. 4 — User authentication]]
 
The VHSM server is responsible for user authentication, interaction with the secure storage, and performing cryptographic operations.
 
The VHSM server is responsible for user authentication, interaction with the secure storage, and performing cryptographic operations.
−
A client must be registered in the system to work with VHSM, so it reports its credentials to the VHSM admin. 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.
+
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.  
−
A user is authenticated 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 where one can get access to the VHSM from. If the user attempts to access to the VHSM from a non-authorized container the request is refused.
+
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 where one can get access to the VHSM from. If the user attempts to access to the VHSM from a non-authorized container the request is refused.
  
 
=== Transport ===
 
=== Transport ===
−
The data exchanging protocol between clients and the VHSM is written in the [https://code.google.com/p/protobuf/ Protocol Buffers] language. On the one hand, it allows to easily extend the protocol, on the other it's more space efficient compared to XML. In general, a protocol message contains parameters of the API function being called and some service information as well.
+
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.
−
As mentioned above, 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 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. 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.
 
  
 
=== Client virtual environment ===
 
=== Client virtual environment ===
−
The client part of the VHSM consists from the API-library and some auxiliary tools (such as [http://www.openssl.org/docs/crypto/engine.html OpenSSL engines]).
+
[[File:Vhsm_pkcs11_mapping.png|thumb|right|400px|Fig. 5 — PKCS#11 slots and VHSM users]]
−
The VHSM API library provides PKCS#11-like functions for managing sessions and user keys and for digital signing.
+
The client part of the VHSM consists from the API-library and some auxiliary tools.
−
Client applications may directly call library functions or may use OpenSSL extensions. The VHSM API allows the user to import or generate some secret data (keys). These data is encrypted by AES-GCM algorithm using the user master key and then stored in the database. Then the user gets the data id which allows to use these data in the future.  
+
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.
−
If the user wants to perform a cryptographic operation then one tells key id for this operation to the VHSM. The VHSM extracts the key from the storage, decrypts it and performs computations in its isolated virtual environment while the user gets the result of the operation only.
+
Here the list of VHSM-specific features:
−
OpenSSL can act as a layer between a client application and the VHSM API library. To achieve that OpenSSL engines can be used. Engines extend the functionality of the OpenSSL and allow to override implementation of some cryptographic algorithms. For example, OpenSSL engines make it possible to use a physical cryptographic device without modifying the code of the client program.
+
* '''Supported object classes'''
 +
*: Currently only <tt>CKO_SECRET_KEY</tt> with key types <tt>CKK_GENERIC_SECRET, CKK_AES</tt> is supported
 +
* '''Supported mechanisms'''
 +
** encryption: <code>CKM_AES_CTR</code> (actually it's AES-GCM)
 +
** digest: <code>CKM_SHA_1</code>
 +
** signing: <code>CKM_SHA_1_HMAC</code>
 +
** key generation: <code>CKM_GENERIC_SECRET_KEY_GEN</code>
 +
* '''Unsupported functions'''
 +
** slot management: <code>C_InitToken, C_InitPin, C_SetPin, C_WaitForSlotEvent</code>
 +
** session management: <code>C_GetOperationState, C_SetOperationState </code>
 +
** object management: <code>C_CopyObject</code>
 +
** signing: <code>C_SignRecoverInit, C_SignRecover, C_VerifyRecoverInit, C_VerifyRecover</code>
 +
** key management: <code>C_GenerateKeyPair, C_WrapKey, C_UnwrapKey, C_DeriveKey</code>
 +
** all dual functions
 +
* '''Additional VHSM-specific functions'''
 +
** <code>VHSM_GetUserSlot</code> returns slotID for the specified user
 +
** <code>VHSM_ImportSecretKey</code> imports secret key with the default template
 +
** <code>VHSM_GetObjectById</code> returns object handle without use of <code>C_FindObjects</code>
 +
*: 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
 +
* '''User flags'''
 +
*: VHSM users have associated flags that determine which functions can be called by the user
 +
** <tt>VF_READ</tt> — read-only functions (like encryption, signing, etc)
 +
** <tt>VF_CREATE</tt> — user can create objects
 +
** <tt>VF_MODIFY</tt> — user can change objects attributes
 +
** <tt>VF_DELETE</tt> — user can destroy objects
 +
** <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
 +
* '''PKCS#11 slot / token selection'''
 +
*: 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.
 +
* '''Multithreading'''
 +
*: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.
  
 
== Building ==
 
== Building ==
  
−
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]
+
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.
  
 
{| class="standard" border="1"
 
{| class="standard" border="1"
Line 72: Line 168:
  
 
You may use binary packages or install manually:
 
You may use binary packages or install manually:
−
* VHSM VE: <tt>vhsm, vhsm_admin</tt>
+
* VHSM VE: <tt>vhsm</tt>
−
* Client VE: <tt>libvhsmapi.so, vhsm_user_admin</tt>
+
* Client VE: <tt>libvhsmapi.a, vhsm_admin</tt>
−
* Host: <tt>vhsm_transport.ko</tt>
+
* Host: <tt>vhsm_transport.ko, vhsm_admin</tt>
  
 
== Usage ==
 
== Usage ==
  
 
To run VHSM perform the following steps:
 
To run VHSM perform the following steps:
−
# insert transport module: <code>insmod vhsm_transport.ko vhsm_veid=%veid%</code> where %veid% is VEID of the VHSM container
+
# Insert transport module: <code>insmod vhsm_transport.ko vhsm_veid=[veid]</code> where <code>[veid]</code> is VEID of the VHSM container
−
# create secure storage in the VHSM VE: <code>vhsm_admin i /path/to/storage</code>
+
# 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 user: <code>vhsm_admin c /path/to/storage login password</code>
+
# Add VHSM users from host: <code>vhsm_admin user create <admin login> <admin password> [options...]</code>. Run <code>vhsm_admin help</code> for details.
−
# start VHSM in the VHSM container. You can specify the path to the secure storage in program arguments
+
# Now you can use VHSM from client VEs
−
# run <code>vhsm_user_admin</code> from client VE
 

Revision as of 19:41, 5 April 2014

Virtual HSM (VHSM) is a software suite for storing and manipulating secret data outside the virtualized application environment. While HSM is a physical device connected to the computer, this software provides HSM functionality through the PKCS#11 API in virtual environment based on OpenVZ container technology.

Structure

Fig. 1 — VHSM overview

The architecture of the Virtual HSM is shown in the Fig. 1. The project consists of the following key components:

VHSM virtual environment
VHSM VE is the isolated environment that contains the VHSM server and secure storage. The server performs operations on secret data and storage keeps encrypted user data
Transport layer
transport exchanges data between client and server virtual environments; based on Netlink
Client virtual environment
client API and accompanying utilities for accessing the VHSM server from a client environment

Details

VHSM virtual environment

Fig. 2 — Data encryption in the VHSM

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 generated from the user password using 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:

Data Type Encrypted Comments
Key ID string no keys in the VHSM can be accessed by their string-ID
Key data blob yes encrypted key data (see the Fig. 2)
Key attributes blob no data structure that holds PKCS#11 key attributes
Import date date-time no key creation date
User name string no VHSM user login
User auth key blob no binary data for the user password check
User type integer no CKU_USER or CKU_SO from the PKCS#11 standard
User flags integer no Flags determine access rights (read, write, delete) for the user
Password derivation params integer no PBKDF2 params used for master key derivation (refer the Fig. 3)
User VEIDs integer no List of VEIDs where the user can get access to the VHSM
Fig. 3 — User registration
Fig. 4 — User authentication

The VHSM server is responsible for user authentication, interaction with the secure storage, and performing cryptographic operations. A client must be registered in the system to work with VHSM. VHSM admins (users with CKU_SO 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 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 Fig. 3.

A user is authenticated (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 where one can get access to the VHSM from. If the user attempts to access to the VHSM from a non-authorized container the request is refused.

Transport

The data exchanging protocol between clients and the VHSM is written in the 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.

Client virtual environment

Fig. 5 — PKCS#11 slots and VHSM users

The client part of the VHSM consists from the API-library and some auxiliary tools. The VHSM API library partially implements PKCS#11 v2.20 standard and provides some additional functions for the user management. Here the list of VHSM-specific features:

  • Supported object classes
    Currently only CKO_SECRET_KEY with key types CKK_GENERIC_SECRET, CKK_AES is supported
  • Supported mechanisms
    • encryption: CKM_AES_CTR (actually it's AES-GCM)
    • digest: CKM_SHA_1
    • signing: CKM_SHA_1_HMAC
    • key generation: CKM_GENERIC_SECRET_KEY_GEN
  • Unsupported functions
    • slot management: C_InitToken, C_InitPin, C_SetPin, C_WaitForSlotEvent
    • session management: C_GetOperationState, C_SetOperationState
    • object management: C_CopyObject
    • signing: C_SignRecoverInit, C_SignRecover, C_VerifyRecoverInit, C_VerifyRecover
    • key management: C_GenerateKeyPair, C_WrapKey, C_UnwrapKey, C_DeriveKey
    • all dual functions
  • Additional VHSM-specific functions
    • VHSM_GetUserSlot returns slotID for the specified user
    • VHSM_ImportSecretKey imports secret key with the default template
    • VHSM_GetObjectById returns object handle without use of C_FindObjects
    Following functions can be called only by CKU_SO user:
    • VHSM_CreateUser creates a new VHSM user using the given template
    • VHSM_ModifyUser allows to set user flags and VEIDs for the specified user
    • VHSM_DeleteUser removes user and all associated data by user name
  • User flags
    VHSM users have associated flags that determine which functions can be called by the user
    • VF_READ — read-only functions (like encryption, signing, etc)
    • VF_CREATE — user can create objects
    • VF_MODIFY — user can change objects attributes
    • VF_DELETE — user can destroy objects
    • VF_CREATE_EXTENDED — user can create CKU_SO users. Only root user (created during VHSM installation) can has this flag
  • PKCS#11 slot / token selection
    In the VHSM slots and tokens are abstract because users are authenticated by login/password pair. In fact, C_GetSlotList 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. Fig. 5 shows how it works.
  • Multithreading
    Each thread must call C_Initialize 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 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 engine_pkcs11, ibmpkcs11 with VHSM.

Building

Install the following packages to build the project on your system. On CentOS use EPEL repositories. In addition, VHSM uses some gcc-specific features, so gcc 4+ is required.

Package Debian CentOS
CMake 2.8 cmake cmake28
OpenVZ kernel headers linux-headers-2.6.32-5-openvz vzkernel-headers
Google protobuf compiler protobuf-compiler protobuf-compiler
libprotobuf libprotobuf-dev protobuf-devel
crypto++ 5.6.2 libcrypto++-dev cryptopp-devel
SQLite 3 libsqlite3-dev sqlite-devel
cppunit (optional) libcppunit-dev cppunit-devel

To build the project just run cmake and then make. You may build binary packages with the command make pkg.

Installation

You may use binary packages or install manually:

  • VHSM VE: vhsm
  • Client VE: libvhsmapi.a, vhsm_admin
  • Host: vhsm_transport.ko, vhsm_admin

Usage

To run VHSM perform the following steps:

  1. Insert transport module: insmod vhsm_transport.ko vhsm_veid=[veid] where [veid] is VEID of the VHSM container
  2. Start VHSM in the VHSM container: vhsm /path/to/storage. You can init secure storage and create root-user on the first run
  3. Add VHSM users from host: vhsm_admin user create <admin login> <admin password> [options...]. Run vhsm_admin help for details.
  4. Now you can use VHSM from client VEs
Retrieved from "https://wiki.openvz.org/index.php?title=Virtual_HSM&oldid=15231"