Detailed description

HSM user management.

Type Definitions
typedef int(AAP_API *	funcListUsersCallback) (char szUserName, void pParam, BOOL bFinal)

Functions
int AAP_API	DCreateUser (HSESSIONCTX hSession, struct USER_INFO userInfo)

int AAP_API	DRemoveUser (HSESSIONCTX hSession, char *szUserId)

int AAP_API	DSetUserParam (HSESSIONCTX hSession, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetUserParam (HSESSIONCTX hSession, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DListUsers (HSESSIONCTX hSession, funcListUsersCallback fncallback, void *pParam)

int AAP_API	DAssignToken (const HSESSIONCTX hSession, const char szUserId, const DWORD dwParam, BYTE pbData, const DWORD dwDataLen)

int AAP_API	DUnassignToken (const HSESSIONCTX hSession, const DWORD dwParam, const char *szUserId)

int AAP_API	DOATHResync (const HSESSIONCTX hSession, char szUser, char szOTP1, char *szOTP2, DWORD dwParam)

Type definitions

◆ funcListUsersCallback

typedef int(AAP_API * funcListUsersCallback) (char *szUserName, void *pParam, BOOL bFinal)

#include <dinamo.h>

Pointer to callback function for listing users.

Parameters

[in]	szUserName	User name.
[in]	pParam	Pointer to a parameter passed to the DListUsers() function.
[in]	bFinal	Flag indicating the last record.

Return: 0

Functions

◆ DCreateUser()

int AAP_API DCreateUser	(	HSESSIONCTX	hSession,
		struct USER_INFO	userInfo )

#include <dinamo.h>

Create a user in HSM according to the information provided.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	userInfo	Structure containing information for user creation. For more details, see the comments.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes

The user authorization mask, contained in the structure USER_INFOmust be assembled by concatenating the values below:

Value	Meaning
ACL_NOP	User with ordinary authorizations only.
ACL_OBJ_CREATE	Permission to create objects. Read permission(ACL_OBJ_READ) is assigned implicitly.
ACL_OBJ_DEL	Permission to remove objects. Read permission(ACL_OBJ_READ) is assigned implicitly.
ACL_OBJ_READ	Permission to read the contents of objects.
ACL_OBJ_UPDATE ACL_OBJ_WRITE	Permission to update object attributes. ACL_OBJ_UPDATE = ACL_OBJ_WRITE
ACL_USR_CREATE ACL_USR_DELETE	Permission to create and remove users. ACL_USR_CREATE = ACL_USR_DELETE
ACL_USR_REMOTE_INFO	Permission to receive remote log notifications.
ACL_USR_LIST	Permission to list users.
ACL_SYS_OPERATOR	Permission to operate as the user 'master'.
ACL_SYS_BACKUP ACL_SYS_RESTORE	Permission to create and restore backup copies of HSM data. ACL_SYS_BACKUP = ACL_SYS_RESTORE
ACL_SYS_UDATE_HSM	Permission to update the firmware.
ACL_NS_AUTHORIZATION	Enables the M of N partition. Authorization of the partition is done via M of N through the local console.
ACL_LOCAL_CRYPTO	Enable Local-crypto. The encryption operations of the partition keys will be performed by the local console.

Examples: user_add_remove.c and user_otp.c.

◆ DRemoveUser()

int AAP_API DRemoveUser	(	HSESSIONCTX	hSession,
		char *	szUserId )

#include <dinamo.h>

Removes a user from HSM.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szUserId	User identifier within the HSM. This identifier must not contain spaces or special characters. Uppercase and lowercase characters are case-sensitive.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: The removal of users also causes the removal of all objects in their possession, including keys and files.

Attention: This function should be used with caution, as all objects owned by the removed user will also be permanently deleted from the HSM. It is recommended that you create a backup copy before performing this function.

Examples: user_add_remove.c and user_otp.c.

◆ DSetUserParam()

int AAP_API DSetUserParam	(	HSESSIONCTX	hSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Change user settings on Dinamo.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwParam

Specifies the session parameter to be configured and consequently the data structure passed in the parameter pbData.

Value	Meaning
UP_USER_NAME	Type of `pbData:` char * User name associated with the current identifier. `pbData` should be a pointer to a string containing the user's name. Not yet supported.
UP_AUTH_MASK	Type of `pbData:` USER_INFO * Bitmask containing the current user's authorizations. See API DCreateUser().
UP_ACCESS_TYPE	Type of `pbData:` DWORD Type of access allowed for the current user. Not yet supported.
UP_PASSWORD	Type of pbData: char * Changes the current user's password. `pbData` should be a pointer to a string that will contain the user's new password.
UP_CERTIFICATE	Type of `pbData:` USER_INFO_CERT * The structure can be filled with an X.509 v3 certificate encoded in DER or PEM if associated with the current user. For token disassociation it is not necessary to fill in the certificate fields in the structure USER_INFO_CERT.
UP_BLOCK_USR	Type of pbData: char * Blocks the user specified in pbData. `pbData` must point to a string containing the user to be blocked.
UP_UNBLOCK_USR	Type of pbData: char * Unlocks the user specified in pbData. `pbData` must point to a string containing the user to be unlocked.

[in] pbData Pointer to the data or structures specified in dwParam.

[in] dwDataLen Size of data or structure specified in dwParam.

[in] dwFlags Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: When dwParam is equal to UP_PASSWORD, the user's new password takes effect as soon as the function returns, so all subsequent authentications must be done with the new value.
The user's authorization mask must be assembled by concatenating the values in the table described in DCreateUser().

◆ DGetUserParam()

int AAP_API DGetUserParam	(	HSESSIONCTX	hSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recover user settings from Dinamo.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwParam

Consult dwParam in DSetUserParam(). The table below describes the specific flags for this API.

Value	Meaning
UP_BLOCK_USR	Type of `pbData:` USER_BLOCK Structure that will receive the user's lock data. Fill in the szUserId member of the structure for input. The nBlocked member will be filled in by the API.
UP_INVALID_LOGIN_ATTEMPTS	Type of `pbData:` USER_BLOCK Structure that will receive the user's invalid login attempt data. Fill in the szUserId member of the structure for input. The dwAttempts member will be filled in by the API. This value will be returned when the invalid login attempts option is set in the password policy.
UP_USR_PA_STATE	Type of `pbData:` USER_PA_INFO Structure that will receive the split authorization data. Fill in the szUserId member of the structure for input. The other members will be filled in by the API.

[in] pbData Pointer to the data or structures specified in dwParam.

[in] pdwDataLen Size of data or structure specified in dwParam.

[in] dwFlags Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

◆ DListUsers()

int AAP_API DListUsers	(	HSESSIONCTX	hSession,
		funcListUsersCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Lists the users of Dinamo.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	fncallback	Pointer to a callback function used to list user names (identifiers).
[in]	pParam	Pointer to any parameter that will be passed to the callback function

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: user_add_remove.c.

◆ DAssignToken()

int AAP_API DAssignToken	(	const HSESSIONCTX	hSession,
		const char *	szUserId,
		const DWORD	dwParam,
		BYTE *	pbData,
		const DWORD	dwDataLen )

#include <dinamo.h>

It associates a standard OTP (time or event) token OATH with a user. After this call, the user will only authenticate with user, password and OTP.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwParam

The following table is accepted:

Value	Meaning
AT_OATH_TOKEN	Associates a HOTP(event) token with the user. Pass OATH_SA_v1 in pbData.
AT_OATH_TOKEN_TOTP	Associate a TOTP(time) token with the user. Pass OATH_SA_v2 in pbData.

[in] szUserId Name of the user who will have the token associated.

[in] pbData Data containing the token parameters. Must be specified as defined in the dwParam parameter.

[in] dwDataLen Size, in bytes, of the data passed in pbData.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Notes: As of firmware version 4.0.2, the size of the authentication look-ahead window is set to the default of 10 intervals more or less. In the case of HOTP tokens, the intervals will be counted by the number of events, while in the case of TOTP tokens they will be counted by the number of time-steps.

Examples: user_otp.c.

◆ DUnassignToken()

int AAP_API DUnassignToken	(	const HSESSIONCTX	hSession,
		const DWORD	dwParam,
		const char *	szUserId )

#include <dinamo.h>

Disassociates OTP authentication from a user. After this call, the user will only authenticate with username and password.

Parameters

[in] hSession Context acquired through the DOpenSession() function.

[in]

dwParam

The following table is accepted:

Value	Meaning
AT_OATH_TOKEN	Disassociates a HOTP (event) or TOTP (time) token from the user.

[in] szUserId Name of the user who will have their token disassociated.

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: user_otp.c.

◆ DOATHResync()

int AAP_API DOATHResync	(	const HSESSIONCTX	hSession,
		char *	szUser,
		char *	szOTP1,
		char *	szOTP2,
		DWORD	dwParam )

#include <dinamo.h>

Re-synchronizes an event token, standard OATH, associated with an HSM user. It receives two consecutive OTPs, generated by the token, to synchronize the state of the token in the HSM user.

Parameters

[in]	hSession	Context acquired through the DOpenSession() function.
[in]	szUser	Name of the user who will have their token re-synchronized.
[in]	szOTP1	First OTP, for synchronization, generated by the token.
[in]	szOTP2	Second OTP, for synchronization, generated by the token.
[in]	dwParam	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

Examples: user_otp.c.

Detailed description

Type Definitions

Functions

Type definitions

◆ funcListUsersCallback

Functions

◆ DCreateUser()

◆ DRemoveUser()

◆ DSetUserParam()

◆ DGetUserParam()

◆ DListUsers()

◆ DAssignToken()

◆ DUnassignToken()

◆ DOATHResync()