Usuários

Descrição detalhada

Gerência de usuários do HSM.

Consulte a documentação técnica do HSM.

Definições de Tipos
typedef int(AAP_API *	funcListUsersCallback) (char *szUserName, void *pParam, BOOL bFinal)

Funções
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)

Definições dos tipos

funcListUsersCallback

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

#include <dinamo.h>

Ponteiro para função de callback para listagem de usuários.

Parâmetros

[in]	szUserName	Nome do usuário.
[in]	pParam	Ponteiro para um parâmetro passado para a função DListUsers().
[in]	bFinal	Flag que indica o último registro.

Retorna

0

Funções

DCreateUser()

int AAP_API DCreateUser	(	HSESSIONCTX	hSession,
		struct USER_INFO	userInfo )

#include <dinamo.h>

Cria um usuário no HSM de acordo com as informações indicadas.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	userInfo	Estrutura contendo informações para a criação do usuário. Para mais detalhes, veja as observações.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

A máscara de autorização do usuário, contida na estrutura USER_INFO, deverá ser montada a partir da concatenação dos valores abaixo:

Valor	Significado
ACL_NOP	Usuário apenas com autorizações ordinárias.
ACL_OBJ_CREATE	Permissão para criar objetos. A permissão de leitura (ACL_OBJ_READ) é atribuída implicitamente.
ACL_OBJ_DEL	Permissão para remover objetos. A permissão de leitura (ACL_OBJ_READ) é atribuída implicitamente.
ACL_OBJ_READ	Permissão para ler o conteúdo de objetos.
ACL_OBJ_UPDATE ACL_OBJ_WRITE	Permissão para atualizar atributos dos objetos. ACL_OBJ_UPDATE = ACL_OBJ_WRITE
ACL_USR_CREATE ACL_USR_DELETE	Permissão para criar e remover usuários. ACL_USR_CREATE = ACL_USR_DELETE
ACL_USR_REMOTE_INFO	Permissão para receber notificações de log remota.
ACL_USR_LIST	Permissão para listar usuários.
ACL_SYS_OPERATOR	Permissão para operar como o usuário ‘master’.
ACL_SYS_BACKUP ACL_SYS_RESTORE	Permissão para criar e restaurar cópias de segurança dos dados do HSM. ACL_SYS_BACKUP = ACL_SYS_RESTORE
ACL_SYS_UDATE_HSM	Permissão para atualizar o firmware.
ACL_NS_AUTHORIZATION	Habilita o M de N de partição. A authorização da pertição é feita via M de N através da console local.
ACL_LOCAL_CRYPTO	Habilita o Local-crypto. As operações de criptografia das chaves da partição serão feitas pela console local.

Exemplos

user_add_remove.c e user_otp.c.

DRemoveUser()

int AAP_API DRemoveUser	(	HSESSIONCTX	hSession,
		char *	szUserId )

#include <dinamo.h>

Remove um usuário do HSM.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szUserId	Identificador do usuário dentro do HSM. Este identificador não deve conter espaços ou caracteres especiais. Caracteres maiúsculos e minúsculos são diferenciados (case-sensitive).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

A remoção dos usuários causa também a remoção de todos os objetos que são de sua posse, o que inclui chaves e arquivos.

Atenção

Esta função deve ser usada com cautela, já que todos os objetos de posse do usuário removido também serão excluídos permanentemente do HSM. É recomendável criar uma cópia de segurança antes de executar essa função.

Exemplos

user_add_remove.c e user_otp.c.

DSetUserParam()

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

#include <dinamo.h>

Altera configurações dos usuários do Dinamo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	Especifica o parâmetro da sessão que deve ser configurado e por conseqüência a estrutura de dados passados no parâmetro pbData. Valor Significado UP_USER_NAME Tipo de pbData: char * Nome do usuário associado ao identificador corrente. pbData deverá ser um ponteiro para uma string que conterá o nome do usuário. Ainda não suportado. UP_AUTH_MASK Tipo de pbData: USER_INFO * Máscara de bits contendo as autorizações do usuário corrente. Veja API DCreateUser(). UP_ACCESS_TYPE Tipo de pbData: DWORD Tipo de acesso permitido para o usuário corrente. Ainda não suportado. UP_PASSWORD Tipo de pbDada: char * Altera a senha do usuário corrente. pbData deve ser um ponteiro para uma string que conterá a nova senha do usuário. UP_CERTIFICATE Tipo de pbData: USER_INFO_CERT * A estrutura poderá ser preenchida com um certificado X.509 v3 codificado em DER ou PEM no caso de associado ao usuário corrente. Para desassociação de token não é necessário preeencher os campos de certificado na estrutura USER_INFO_CERT. UP_BLOCK_USR Tipo de pbDada: char * Bloqueia o usuário especificado em pbData. pbData deve apontar para uma string contendo o usuário que deverá ser bloqueado. UP_UNBLOCK_USR Tipo de pbDada: char * Desbloqueia o usuário especificado em pbData. pbData deve apontar para uma string contendo o usuário que deverá ser desbloqueado.
[in]	pbData	Ponteiro para os dados ou estruturas especificados em dwParam.
[in]	dwDataLen	Tamanho dos dados ou estrutura especificados em dwParam.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Quando dwParam é igual a UP_PASSWORD a nova senha do usuário passa a valer assim que a função retorna, dessa maneira, todas autenticações subseqüentes devem ser feitas com o novo valor.
A máscara de autorização do usuário deverá ser montada a partir da concatenação dos valores da tabela descrita em DCreateUser().

DGetUserParam()

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

#include <dinamo.h>

Recupera as configurações dos usuários do Dinamo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	Consulte dwParam em DSetUserParam(). A tabela abaixo descreve as flags específicas para esta API. Valor Significado UP_BLOCK_USR Tipo de pbData: USER_BLOCK Estrutura que receberá os dados de bloqueio do usuário. Preencher o membro szUserId da estrutura para entrada. O membro de nBlocked será preenchido pela API. UP_INVALID_LOGIN_ATTEMPTS Tipo de pbData: USER_BLOCK Estrutura que receberá os dados de tentativas de login inválido do usuário. Preencher o membro szUserId da estrutura para entrada. O membro de dwAttempts será preenchido pela API. Este valor será retornado quando a opção de tentativas de login inválido for definida na política de senhas. UP_USR_PA_STATE Tipo de pbData: USER_PA_INFO Estrutura que receberá os dados de autorização de partição. Preencher o membro szUserId da estrutura para entrada. Os outros membros serão preenchidos pela API.
[in]	pbData	Ponteiro para os dados ou estruturas especificados em dwParam.
[in]	pdwDataLen	Tamanho dos dados ou estrutura especificados em dwParam.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DListUsers()

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

#include <dinamo.h>

Lista os usuários do Dinamo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	fncallback	Ponteiro para uma função de callback usada para listar os nomes (identificadores) dos usuários.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

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>

Associa um token OTP(de tempo ou evento) padrão OATH a um usuário. Após esta chamada o usuário fará autenticação apenas com usuário, senha e OTP.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	A seguinte tabela é aceita: Valor Significado AT_OATH_TOKEN Associa um token HOTP(de evento) ao usuário. Passar OATH_SA_v1 em pbData. AT_OATH_TOKEN_TOTP Associa um token TOTP(de tempo) ao usuário. Passar OATH_SA_v2 em pbData.
[in]	szUserId	Nome do usuário que terá o token associado.
[in]	pbData	Dados contendo os parâmetros do token. Deve ser especificado de acordo com o definido no parâmetro dwParam.
[in]	dwDataLen	Tamanho, em bytes, dos dados passados em pbData.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

A partir da versão 4.0.2 do firmware o tamanho da janela de look-ahead de autenticação é definida com o padrão de de 10 intervalos para mais ou para menos. No caso de tokens HOTP os intervalos serão contados por quantidade de eventos, no caso dos tokens TOTP serão contados por quantidade de time-steps.

Exemplos

user_otp.c.

DUnassignToken()

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

#include <dinamo.h>

Desassocia a autenticação com OTP de um usuário. Após esta chamada o usuário fará autenticação apenas com usuário e senha.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	A seguinte tabela é aceita: Valor Significado AT_OATH_TOKEN Desassocia um token HOTP(de evento) ou TOTP(de tempo) do usuário.
[in]	szUserId	Nome do usuário que terá o seu token desassociado.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

user_otp.c.

DOATHResync()

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

#include <dinamo.h>

Re-sincroniza um token de eventos, padrão OATH, associado a um usuário do HSM. Recebe dois OTPs consecutivos, gerados pelo token, para sincronizar o estado do token no usuário do HSM.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szUser	Nome do usuário que terá o seu token re-sincronizado.
[in]	szOTP1	Primeiro OTP, para sincronização, gerado pelo token.
[in]	szOTP2	Segundo OTP, para sincronização, gerado pelo token.
[in]	dwParam	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Exemplos

user_otp.c.