Introduction

This documentation describes HSM's proprietary APIs, with data structures, functions, return codes and examples. Please also refer to the Client Software Manual regarding the configuration of library parameters, such as load balancing and session caching; some of these parameters influence the functioning of the APIs.

The HSM APIs allow the use of security/encryption features in applications, however this manual does not cover or discuss security/encryption theory or the details, such as the strengths and weaknesses of each specific algorithm or protocol design. Cryptography is a complex and advanced subject, it is always advisable to consult a solid and recent reference to make the best use of HSM. Always try to understand what you are doing and why you are doing it. Don't simply copy code to solve the problems in your scenario. Many applications have already been developed with serious security problems simply because the wrong tool was chosen.

Programming interface

HSM Dinamo provides a very rich and versatile client programming interface, allowing quick and easy integration into any type of application. Dinamo Networks provides an API for Windows, Unix and Linux platforms in the Dinamo package. Consult for specific versions of Unix and Linux or other platforms.

Observation: HSM sessions have session-thread affinity. This means that the same session cannot be used by several threads at the same time.

The communication sessions opened by the client to the Dinamo service can be encrypted or open. When encrypted, the TLS (Transport Layer Security) protocol is used. There is an inactivity timeout of 05 (five) minutes, i.e. after a period of 20 minutes without requests from the client to the server, the Dinamo service immediately terminates the client session and only by opening a new connection (with new authentication) will the client be able to communicate with Dinamo again. This timeout prevents sessions from crashing and adds a level of security to the channel.

There is a limit of 07 simultaneous sessions that can receive log notifications.

The HSM Dinamo has been designed with highly optimized symmetric and asymmetric key management, both in terms of performance on the client and in the HSM, and ease of programming. Key generation, recovery and removal operations are atomic, and each key has a unique identifier. The specific attributes of each key (type, size, value, exportable, encrypted, etc.) are stored in cache structures, which offers a substantial performance gain without compromising security. All keys stored internally with the encryption attribute enabled are encrypted by the SVMK (Server Master Key), which in turn is only introduced into the system after authentication via the smart card, and is only kept in volatile memory.

Removing keys is a definitive operation and there is no way to recover deleted keys, so the application must program checking mechanisms before proceeding with a key removal operation. A message jammed by a deleted key will be virtually lost, as only a brute force attack will be able to recover the message, which may be computationally unfeasible.

The probe function allows you to check the status of Dinamo with minimal traffic and processing.

Observation: Dinamo Networks is constantly improving its products, so it is possible to find small discrepancies between the documentation and the product received. If you have any questions, please feel free to contact Dinamo Networks support to clarify your doubts.

See the User Manual for configuration parameter options for the Native API.

In the description of the parameters, [in] will be used to indicate that the value of this parameter must be filled in before the function is called (input parameter), [out] to indicate that the value will be filled in internally in the function and returned in the output (output parameter) and [in/out] to indicate that the parameter must be filled in before the function is called and can be changed internally (bidirectional parameter).

All functions exported from the Dinamo libraries have their name prefixed with the letter "D".

The programming interfaces in different languages available for the HSM:

Information such as features, initialization, management, integration and more can be found in the HSM technical documentation.