sdk - neoprot.com.br · p | seguro, fácil e rápido. roteção e licenciamento no seu software....

| Seguro, fácil e rápido.

Proteção e licenciamento

no seu software.

SDK Manual do Desenvolvedor v 2.0.7

NeoKey

2

NeoKey SDK versão 2.0.7

ÍNDICE .......................................................................................................................................................... 4

LINKS RÁPIDOS .......................................................................................................................................... 5

NEOKEY ....................................................................................................................................................... 6

SISTEMAS OPERACIONAIS SUPORTADOS ...................................................................................................... 7

MÍNIMO HARDWARE REQUERIDO .................................................................................................................. 7

CARACTERÍSTICAS FÍSICAS .......................................................................................................................... 7

DEVTOOL ..................................................................................................................................................... 8

TABELA A (ERROS NO DEVTOOL) ................................................................................................................. 8

PROTEÇÃO AUTOMÁTICA ....................................................................................................................... 21

NEOKEY MASTER ..................................................................................................................................... 22

NEOKEY NOW ........................................................................................................................................... 24

CLIENTAPI ................................................................................................................................................. 25

TABELA 1 (ERROS NA CLIENTAPI) .............................................................................................................. 25

NEOKEYCALL ............................................................................................................................................ 29

TABELA 2 (COMANDOS) ............................................................................................................................. 30

Login - cmd = 1 ................................................................................................................................... 31

Gravar na Memória (DWORD) - cmd = 2 ........................................................................................... 32

Ler da memória (DWORD) - cmd = 3 ................................................................................................. 32

Criptografar - cmd = 4 ......................................................................................................................... 32

Descriptografar - cmd = 5 ................................................................................................................... 33

Ler a licença - cmd = 7 ........................................................................................................................ 34

Gravar na Memória (WORD) - cmd = 8 ............................................................................................. 34

Ler da memória (WORD) - cmd = 9 ................................................................................................... 35

Ler ID do Hardware - cmd = 10 ........................................................................................................... 35

Ler uma página da memória - cmd = 11 ............................................................................................. 35

Gravar uma página na memória - cmd = 12 ....................................................................................... 36

Buscar próximo NeoKey - cmd = 14 ................................................................................................... 36

Reiniciar busca - cmd = 15 ................................................................................................................. 37

Logout - cmd = 16 ............................................................................................................................... 37

Ler o código de atualização (CDC) - cmd = 31 ................................................................................... 37

Aplicar atualização via código (CPC) - cmd = 32 ............................................................................... 38

Aplicar atualização via arquivo (CPC) - cmd = 33 .............................................................................. 38

SetSinc - cmd = 53 .............................................................................................................................. 38

SincOTP - cmd = 50 ............................................................................................................................ 39

LoginOTP - cmd = 51 .......................................................................................................................... 39

FUNÇÕES NEOKEY_ .................................................................................................................................. 40

NeoKey_Login OU NeoKey_LoginOTP .............................................................................................. 40

NeoKey_SincOTP ............................................................................................................................... 42

NeoKey_Logout .................................................................................................................................. 42

NeoKey_Write ..................................................................................................................................... 42

NeoKey_Read ..................................................................................................................................... 43

NeoKey_Login_Next ........................................................................................................................... 43

NeoKey_Crypt ..................................................................................................................................... 44

NeoKey_Decrypt ................................................................................................................................. 45

3


NeoKey_GetLicense ........................................................................................................................... 45

CLIENTAPI – ARQUIVO DE CONFIGURAÇÃO ................................................................................................ 46

NEOKEYNETSERVICE .............................................................................................................................. 49

NEOKEYNETSERVICE – ARQUIVO DE CONFIGURAÇÃO................................................................................. 49

4


Índice A

Atualização Remota ......................................... 18

C

Características Físicas ....................................... 7

ClientAPI .......................................................... 25

ClientAPI – Arquivo de Configuração .............. 46

Criar um projeto ............................................... 10

D

Desafio-Reposta e Criptografia ........................ 11

DevTool .............................................................. 8

F

Funções NeoKey .............................................. 40

G

Gerar as APIs ................................................... 16

L

Licenças ........................................................... 11

LoginOTP ................................ 31, 39, 40, 41, 42

M

Memória ........................................................... 13

Mínimo Hardware Requerido ............................. 7

N

NeoKey .............................................................. 6

NeoKey Master ................................................ 22

NeoKey NOW .................................................. 24

NeoKey+Net ...................................................... 6

NeoKeyCall ...................................................... 29

NeoKeyNetService........................................... 49

NeoKeyNetService – Arquivo de Configuração

..................................................................... 49

P

Proteção Automática ....................................... 21

S

Salvar e Gravar ................................................ 14

Sistemas Operacionais Suportados .................. 7

5


Links Rápidos www.neoprot.com

[email protected]

[email protected]

NeoKey

Sistemas Operacionais Suportados

Mínimo Hardware Requerido

Características Físicas

DevTool

NeoKey NOW

Proteção Automática

NeoKey Master

ClientAPI

Função NeoKeyCall

Função NeoKey_

NeoKeyNetService

http://www.neoprot.com/

http://www.neoprot.com/

mailto:[email protected]


6


NeoKey

O NeoKey é um pequeno dispositivo USB (similar a um pendrive) que funciona como uma

chave para execução do software protegido. Se o NeoKey estiver conectado em uma porta

USB o software protegido funciona normalmente, mas se o NeoKey não estiver conectado o

software protegido não funciona.

O NeoKey é um hardware compatível HID, portanto não há necessidade de instalação de

qualquer “device driver” adicional para o seu funcionamento, pois todos os drivers necessários

para o seu funcionamento já estão instalados no próprio sistema operacional.

O NeoKey+Net é uma variação do NeoKey, mas que pode ser usado através de uma rede,

usando o NeoKeyNetService.

O NeoKey NOW é um sistema de atualização remota através da Web que permite que as

atualizações da sua licença referentes ao número de execuções, data de expiração e

quantidade de usuários em rede em seus clientes possam ocorrer sem que ele precise enviar

arquivos ou mesmo entrar em contato com sua empresa, bastando somente que ele tenha

acesso a internet. Veja o capítulo NeoKey NOW

O DevTool é um aplicativo que permite ao desenvolvedor configurar/personalizar o NeoKey

para integrá-lo ao seu aplicativo, nele estão contidas todas as funcionalidades do sistema de

proteção e licenciamento. Pelo DevTool você vai gerar um projeto que deverá ser gravado no

NeoKey, neste projeto há informações: para autenticar o NeoKey, das licenças de uso da

chave e o conteúdo da memória, gerar as APIs, proteger automaticamente seu aplicativo e

realizar atualizações remotas no NeoKey.

O NeoKey Master, é um NeoKey especial e permite ao desenvolvedor acessar as

funcionalidades do DevTool.

A integração do seu aplicativo ao NeoKey é realizado por uma API, que é um conjunto de

funções acessadas pelo seu software a fim de interagir com o hardware, realizando diversas

operações como login, gravação, leitura, atualização remota, etc . As APIs são geradas pelo

DevTool, aplicativo que é instalado pelo instalador do NeoKey SDK e são denominadas como

ClientAPI, sendo seu nome diferenciado de acordo com o sistema operacional. A API deve

fazer parte da instalação do seu aplicativo, sendo copiada no diretório do seu aplicativo, no

Recursos

Driver Less

Memória 4 KBytes

Exemplos e APIs

Hardware ID

Criptografia AES-256

Bloqueio de senha

Anti-Debug

64 licenças

Chave Master

Multi-thread

Atualização Remota

NeoKey+Net

7


diretório de sistema ou qualquer diretório com um caminho especificado e conhecido do seu

aplicativo.

Consulte o capítulo do DevTool para maiores detalhes de como gerar a ClientAPI.

Consulte o capítulo da NeoKeyMaster para maiores detalhes do NeoKey Master.

Consulte o capítulo da ClientAPI para maiores detalhes de como acessar a ClientAPI.

Consulte o capítulo da Proteção Automática para maiores detalhes de como proteger seu

software de forma automática sem a necessidade de alterar o seu código fonte.

Consulte o capítulo da NeoKeyNetService para maiores detalhes de como acessar o hardware

através de uma rede.

Sistemas Operacionais Suportados

Atualmente são suportados os sistemas operacionais: Windows 32bit e 64bit (ClientAPI32.dll e ClientAPI64.dll) XP, Vista, 7, 8, 10, 2003, 2008, 2012, 2016. Linux 32bit e 64bit (libClientAPI32.a e libClientAPI64.a) Kernel 2.6: Ubuntu, Fedora, Debian e RedHat MacOS 64bit (libClientAPI64Mac.a)

Mínimo Hardware Requerido

Plataforma PC ou ARM (consulte o suporte técnico), memória 1GB, USB 1.x, 2.x, 3.x e espaço

livre em disco 100MB

Características Físicas

Dimensões: 40 x 20 x 8 mm, Peso: 7 g Consumo de energia: <= 50mA, Voltagem Operacional Mínima: 5V Temperatura de Armazenagem e umidade: –5 a 70ºC e 0 a 70% (sem condensação) Invólucro: Plástico injetável Retenção de dados em memória: Mínimo 10 anos Regravação das células de memória: Mínimo 100.000 vezes/célula.

Notas:

"Este produto inclui software desenvolvido pelo OpenSSL Project para uso no OpenSSL

Toolkit. (http://www.openssl.org/)".

Importante: O sistema de proteção do NeoKey deve ser considerado como mais um elemento

de proteção, que ajuda o desenvolvedor de software a proteger sua propriedade intelectual de

cópias indevidas. E pode ser usado com recursos de terceiros para aumentar o nível de

proteção. Consulte sempre o suporte técnico para verificar se está em acordo com o uso das

melhores práticas de segurança. [email protected]

http://www.openssl.org/)

8


DevTool O DevTool é um aplicativo que permite ao desenvolvedor configurar/personalizar o NeoKey

para integrá-lo ao seu programa, nele estão contidas todas as funcionalidades do sistema de

proteção e licenciamento. (Criar projetos, Gerar APIs, Implementar a Proteção e Atualizar

remotamente o NeoKey)

Todas as funcionalidades relativas ao projeto necessitam de um NeoKey Master

conectado.

Consulte o capítulo da NeoKey Master para maiores detalhes sobre os seus recursos.

A integração do seu aplicativo com o NeoKey, deve passar por 3 etapas básicas:

1) Criar um projeto

2) Gerar as APIs

3) Proteger o aplicativo Via API, consulte os exemplos.

Tabela A (Erros no DevTool)

Descrição Erro

Erro de leitura -5001

Erro na gravação -5002

Erro no Login -5003

Erro no comando -5004

Master não conectado -5006

NeoKey não conectado -5007

Possíveis causas para os erros acima: Os erros -1 e -2 ocorrem, pois os parâmetros iniciais de criptografia de acesso ao NeoKey não foram adequadamente inicializados ou foram corrompidos e por isso ao tentar fazer qualquer acesso no NeoKey o mesmo não consegue decifrar os comandos causando estes erros.

Criar um projeto

Defina o licenciamento

Salve e grave o projeto

Gerar as APIs

Gere as APIs e distribua com o seu produto

Teste o projeto gravado

Proteger seu Software

Automático, selecione o arquivo a ser protegido

Via API, consulte os exemplos.

9


Verifique se o projeto foi gravado corretamente. Verifique se está “logado” no NeoKey. O desafio está correto? O NeoKey está conectado? O Led (luz) do NeoKey está aceso? Caso não esteja o NeoKey pode ter sido danificado ou o computador não o reconheceu. Tente reconectar o NeoKey novamente. Verifique se a porta USB está funcionando corretamente, com um mouse ou teclado USB.

APIs básicas não encontradas -5008

Os sistema operacional não está adequadamente instalado e não será possível acessar o NeoKey.

Master sem previlégio -5009

O Master que está usando está com privilégios de acesso limitados, para realizar uma tarefa.

NeoKey inválido -5010

O NeoKey não possui as características necessárias de configuração para que este SDK e Master.

CDC inválido -5025

Os dados enviados pelo cliente estão incorretos, tente verificar junto ao cliente se ele antou corretamente.

MasterII não conectado -5026

O Segundo master requerido para esta operação não pode ser localizado, verifique se o mesmo está conectado, com led aceso.

Não foi possível salvar o arquivo -5101

Erro ao gravar arquivo de Backup -5300

Arquivo de atualização não encontrado -5450

Os erros acima são causados geralmente for falta de permissão ao usuário que está acessando o sistema, verifique com seu administrador se há direitos de acesso às pastas do sistema.

Web update (NeoKey NOW) não está respondendo corretamente.

-5460

Web update (NeoKey NOW) está bloqueado. -5461

Web update, a conexão com o computador local não pode ser inicializada.

-5462

Possíveis causas para os erros acima: Há algum problema de conexão com a web ou nossos servidores estão indisponíveis, verfique se nosso site www.neoprot.com.br pode ser acessado e se há conexão para internet.

Web update (NeoKey NOW), erro de sintaxe. -5464

Possíveis causas para o erro acima: Esta é uma falha interna em nossos sistemas, verifique junto ao suporte se há atualização do serviço e das APIS.

http://www.neoprot.com.br/

10


Web update (NeoKey NOW), usuário master não autorizado. -5465

Possíveis causas para o erro acima: Para usar o serviço é necessário se cadastrar, solicite junto ao suporte o seu cadastro neste serviço.

Web update (NeoKey NOW), erro geral na pagina. -5466


Web update (NeoKey NOW), limite máximo permitido de NeoKeys na WEB atingido.

-5467

Possíveis causas para o erro acima: Verifique junto ao suporte qual é a quantidade máxima de NeoKeys permitida e cadastrada para você no serviço de Web update.

Criar um projeto

É no projeto que definimos as informações que ficarão armazenadas do NeoKey como:

desafio-resposta (para autenticar a aplicação), a chave de criptografia, licenças de uso do

aplicativo e o conteúdo da memória.

Para criar um projeto basta clicar no botão (Novo), um Wizard vai orientá-lo pelos 4 passos da

criação do projeto.

11


Desafio-Reposta e Criptografia

Aqui configuramos a senha/desafio e a resposta, que será enviado ao hardware posteriormente

pela API, se a chave estiver conectada e a senha/desafio estiver correto, o NeoKey envia a

Resposta, conforme você configurar nesta tela. A chave de criptografia é usada durante o

comando de criptografar e descriptografar.

Gerar Randômicos, ao clicar nele são geradas automaticamente as informações do desafio-

resposta e a chave de criptografia.

Licenças

Neste passo podemos configurar as características das licenças.

12


As licenças são enumeradas de 0 até 63 e acessadas ao realizar um Login, é através da

licença que podemos determinar a data de expiração, o número de execuções e o número de

licenças de rede que seu aplicativo será licenciado.

*Lembre-se de habilitar pelo menos uma licença para que o Login ocorra com sucesso.

Permitindo criar até 64 formas diferentes de licenciamento em um único projeto, este recurso é

muito útil quando há mais de uma aplicação a ser protegida, e você quer usar o mesmo

NeoKey para proteger todas elas. Para realizar esta tarefa basta você determinar qual dos

módulos do seu aplicativo irá acessar cada uma das licenças. Ex: Aplicação de faturamento

acessa a 0, o CRM acessa a 1, o controle de estoque acessa a 2, etc.

Ao clicar em editar ou sobre a linha da licença a tela seguinte é aberta.

Em expiração configuramos se vamos habilitar uma Data de Expiração, podendo ser uma data

pré-determinada ou em número de dias e o número de execuções que é decrementado

somente no primeiro acesso do comando Login, quando a aplicação é carregada.

Em controle de licenças de rede, configuramos quantas instâncias em rede da sua aplicação o

NeoKey permitirá acessá-lo, e se o valor for igual à zero, o acesso pela rede será bloqueado.

Ao selecionar Instância Única, somente uma instância do seu aplicativo por IP será

contabilizada ao acessar esta licença.

Ao selecionar a Desabilitar acesso local, o NeoKey passará a não funcionar localmente na

máquina que estiver conectado, use esta opção somente para o NeoKey+Net quando quiser

forçar seu acesso somente pela rede e desabilitar os acesso locais. Se usar este recurso o seu

NeoKey (comum - acesso mono usuário) esta licença deixará de funcionar.

13


Ao selecionar a opção Desabilitar compartilhamento, resultará que a licença não poderá ser

compartilhada por múltiplas aplicações localmente, ou seja, se mais de uma instância tentar

acessar uma determinada licença somente a primeira funcionará, as demais resultarão em

erro.

Memória

Nesta tela podemos editar o conteúdo da memória. O NeoKey possui um total de 1K DOUBLE

WORDS, endereçados de 0 a 1023.

Lembrando que uma DOUBLE WORD (DWORD) possui 4 bytes, totalizando então 4KBytes

disponíveis para leitura e gravação no NeoKey.

Ao clicar em Editar dados da memória, o editor é habilitado permitindo a edição em Hex

(Hexadecimal) ou Ascii dos endereços desejados. Ao clicar em aplicar modificações o conteúdo

da caixa de texto é transferido para o painel do lado direito.

Ao clicar em Zerar dados, o conteúdo do painel do lado direito passará a conter zeros em todos

os endereços.

14


Salvar e Gravar

Este é último passo, primeiro salve o projeto, num diretório de sua preferência e então clique

em gravar para transferir o projeto para o NeoKey.

Lembre-se que o NeoKey Master será solicitado a cada evento relacionado ao Projeto.

15


Por esta interface é possível associar um NeoKey com determinado cliente, se clicar em sim

um arquivo de log .neokey é gerado na pasta Database, pasta esta localizada na mesma pasta

em que o DevTool está sendo executado. Este arquivo poderá ser consultado posteriormente

para integração com ERPs e sua estrutura de dados possui a seguinte característica de dados

separados por vírgula.

número_do_hardware,nome_do_cliente,id_do_cliente,email,extra_info,data_e_hora,validação

Antes de iniciar a gravação é questionado ao usuário se deseja gravar os dados da memória,

ao responder Sim os 4K bytes referentes ao Passo 3 serão gravados no Neokey, o que deixa o

processo de inicialização mais demorado, se não estiver usando os dados da memória em seu

projeto pode responder Não, deixando o processo mais rápido.

16


No menu principal, ao clicar no botão Abrir, você poderá visualizar um projeto criado.

No menu principal, ao clicar no botão Gravar, você poderá gravar no NeoKey, a partir do

arquivo de um projeto já criado.

No menu principal, ao clicar no botão Ler, você poderá visualizar o projeto gravado dentro de

um NeoKey conectado e salvá-lo em uma pasta.

Gerar as APIs

17


Para gerar as APIs basta clicar em Gerar, então o conjunto de APIs será gerado na pasta APIs.

Este processo precisa ser realizado uma única vez ou quando for realizada alguma atualização

do SDK ou do pacote de APIs através do Menu APIs. O NeoKey Master será solicitado para

esta operação.

Clique em Abrir pasta para acessar a pasta onde as APIs são geradas. Para testar o acesso ao NeoKey, clique em testar, isso vai carregar um exemplo e onde são

acessados todos os recursos disponíveis pela ClientAPI.

Os Exemplos oferecem suporte às Linguagens: o C, C++, C#, VC, VB, Delphi, VB.NET, Java e CAD

Proteger o Aplicativo

Existem 3 formas de proteger seu aplicativo: via o acesso direto às APIs, Automático ou a

combinação destes dois métodos, lembrando que um não inibe a funcionalidade do outro.

Se você optar pela forma automática, não será necessário modificar o código fonte do

aplicativo, basta somente clicar no botão Automático, selecionar o aplicativo, configurar a

licença que será acessada e então proteger. Consulte o capítulo da Proteção Automática

para maiores detalhes.

Se sua opção for pelo acesso via API, então clique no botão Exemplos e acesse os códigos

fontes em diversas linguagens de programação. Caso sua linguagem não esteja disponível

envie um e-mail ao nosso suporte técnico ([email protected]). Teremos o maior prazer

em desenvolver novos exemplos.


18


Uma boa estratégia de proteger seu software significa uma maior dificuldade para usuários mal

intencionados em remover a proteção, para fazer isso aconselhamos, quando possível, usar a

proteção automática em combinação com o acesso via APIs, sempre procure realizar no

mínimo as seguintes etapas.

- O seu programa antes de carregar a API deve gerar um hash (ex:sha1) do arquivo da

ClientAPI a ser acessada, para ser verificado com um valor que gerou antes de distribuir o

programa, isso para identificar a originalidade do arquivo.

- Fazer o Login OTP, utilizando a função SetSinc

- Executar chamadas de criptografia usando o AES-256-ECB e comparar valores que o

Hardware gera. O AES 256 possui código aberto e pode ser acessado de qualquer linguagem,

idealmente deve-se gerar um valor e enviar ao Neokey para ser cifrado, o mesmo deve ser feito

pelo seu programa usando uma função interna AES, e a mesma chave configurada no projeto,

e então comparar os valores.

-Quando não for possível usar a proteção automática deve ser usado “obfuscadores” de

código.

Atualização Remota

Através desta interface você poderá alterar qualquer informação de um NeoKey remotamente.

O sistema de atualização é baseado num esquema de mensagens trocadas entre o cliente e o

desenvolvedor, essas mensagens são denominadas: CDC (Código do cliente) e CPC (Código

para o cliente).

19


O CDC é um conjunto de 32 bytes, código recebido do cliente, gerado pela ClientAPI, único

para cada processo de atualização e deve ser enviado ao desenvolvedor do software, para que

este, através do DevTool gere o CPC (Código para o cliente) que contém as informações de

atualização.

O CPC pode ser um conjunto de 32 bytes ou um arquivo, único para cada processo de

atualização e deve ser enviado ao cliente pelo desenvolvedor do software.

O arquivo .CPC deve ser usado com cuidado, pois ele permite a atualização do NeoKey sem

associar a um número de série (Hardware ID) específico, fazendo com que essa atualização

passe a valer para todos os NeoKeys em campo.

Pelo CDC é possível determinar o número de série (Hardware ID) e saber qual NeoKey em

campo está sendo atualizado, preenchendo o campo CDC e clicando em Validar código.

Clicando em Buscar Cliente com um HardwareID é possível verificar dados de um cliente caso

o tenha associado ao NeoKey quando gravou o projeto ou ainda é possível através do nome do

cliente verificar o número do hardware a ele associado.

Há diversas opções de atualização, que podem ser realizadas para diversos recursos do

NeoKey, como somente uma licença específica ao selecionar as opções (Data e Número de

execuções) ou (Usuários de Rede), todas as licenças ao selecionar Licenças, Memória ou Tudo

para todo o contúdo do NeoKey, inclusive o desafio e a resposta.

O mais comum dos casos de atualização é quando queremos somente atualizar a

característica de uma licença exclusiva, para isso é necessário gerar o CDC através da

ClientAPI no cliente, e preencher o seu valor no campo indicado e selecionar as opções (Data e

Número de execuções) ou (Usuários de Rede). Neste método não é gerado um arquivo de

atualização, mas somente um código CPC de 32 bytes, que é automaticamente associado a

20


um número de série (Hardware ID) do CDC e que poderá ser enviado ao cliente, por email,

telefone, etc. Aplicar atualização via código (CPC) – cmd = 32

Todos os outros métodos geram um arquivo .CPC que podem ou não ser associados a um

número de série, após este arquivo ser enviado ao cliente a atualização deve ocorrer pela

função específica da ClientAPI. Aplicar atualização via arquivo (CPC) – cmd = 33

É possível também gerar um CDC para um determinado NeoKey por seu número de série

(HardwareID), ou seja sem o CDC, bastando preencher número no campo apropriado, para

gerar o CPC.

A opção do NeoKey NOW permite a você atualizar remotamente, pela internet, sem que seu

cliente precise enviar qualquer informação por telefone ou email durante o processo de

atualização. Ao clicar em Remover o update, a atualização através do NeoKey Now deixará de

ocorrer. Veja mais detalhes no capítulo dedicado ao NeoKey NOW

Em campo caso você não programe acesso à API para as funções de atualização é possível

ainda usar o NeoKeyUpdate.exe que está dentro da pasta update para a tarefa de atualizar o

NeoKey. É importante que a ClientAPI esteja no diretório deste aplicativo.

21


Proteção Automática

Este é o método mais simples de proteger seu aplicativo, bastando selecionar o executável ou

dll a ser protegido, o número da licença e o intervalo entre as checagens e então clicando em

Proteger. Lembre-se de copiar a ClientAPI32.dll para a pasta do aplicativo protegido, para

testar.

Atualmente este método é suportado apenas para executáveis e dlls Windows 32 Bit e não

.Net.

22


NeoKey Master No sistema NeoKey há um hardware especial que chamamos de NeoKey Master, responsável

por guardar todas as credenciais para a utilização do NeoKey, por isso deve ser armazenado

em local seguro. Ele permite, por exemplo, o acesso às configurações de um projeto, geração

de APIs e ao menu de atualização.

O Master possui um PIN (senha) para acessá-lo, introduzindo o conceito de autenticação com

duplo fator para acesso ao DevTool e por padrão esta senha é: vazio, mas pode ser alterada a

qualquer momento pelo DevTool, no menu Master.

É possível ainda configurar um outro NeoKey Master, para isso será necessário comprar um

adicional, a fim de a limitar/desabilitar o acesso aos recursos do DevTool ou simplesmente

como backup. Veja abaixo as opções.

É muito comum que seja designado uma pessoa que não é o Desenvolvedor ou dono da

empresa, para gravar o NeoKey recebido da Neoprot e ainda não inicializado, por isso você

pode limitar por exemplo este novo Master a somente permitir o acesso a determinadas

funções, por exemplo: função de gravar/inicializar NeoKeys.

23


Ou ainda você gostaria que pessoa somente conseguisse realizar atualizações.

Durante a configuração de um segundo Master, será necessário o Master original. A senha do

Master a ser configurado será reiniciada para o padrão de fábrica: vazio.

24


NeoKey NOW

O NeoKey NOW (NeoKey Over Web) é um sistema de atualização remoto através da Web que

permite que as atualizações da sua licença referentes ao número de execuções, data de

expiração e quantidades de usuários em rede em seus clientes possam ocorrer sem que ele

precise enviar arquivos ou mesmo entrar em contato com sua empresa, bastando somente que

ele tenha acesso ao site www.neoprot.com.br pela internet. Não há a necessidade de liberar

portas no firewall, mas somente que o site www.neoprot.com.br esteja acessível pelo seu

navegador.

O procedimento de atualização é bastante simples, através do DevTool clicando em Update é

possível gerar os códigos de atualização associado ao número de série (HardwareID) do

NeoKey. Pelo menu opções ao selecionar o NeoKey NOW no final do processo de gerar o CPC

(código de atualização a ser enviado ao seu cliente) é perguntado pelo DevTool se você

gostaria de usar este serviço, clicando em Sim a atualização será submetida diretamente para

nossos servidores e distribuída para o seus clientes de maneira totalmente transparente.

A atualização somente ocorre caso o NeoKey esteja com uma opção de expiração habilitada e

o arquivo de configuração da ClientAPI (ClientAPI32.ini ou ClientAPI64.ini) estiver com a opção

de Webupdate habilitada, por padrão a atualização ocorrerá automaticamente 7 dias antes de

expirar ou quando o número de execuções atingir o valor 20, contudo estes valores também

poderão ser modificados através do arquivo de configuração (ClientAPIxx.ini), veja mais

detalhes em ClientAPI – Arquivo de Configuração

Para usar o serviço entre em contato com o nosso departamento de vendas e veja como

habilitar sua conta. [email protected]




25


ClientAPI A integração do seu aplicativo ao NeoKey é realizada por uma API, que é um conjunto de

funções acessadas pelo seu software a fim de interagir com o hardware, realizando diversas

operações como login, gravação, leitura, atualização remota, etc .

As APIs são geradas pelo DevTool, aplicativo que é instalado pelo instalador do NeoKey SDK e

são denominadas como ClientAPI, sendo seu nome diferenciado de acordo com o sistema

operacional. A API deve fazer parte da instalação do seu produto, sendo esta copiada no

diretório do seu aplicativo, no diretório de sistema ou qualquer diretório com um caminho

especificado e conhecido do seu aplicativo.

A ClientAPI não permite que seu aplicativo seja “debugado”, mesmo no instante do

desenvolvimento, por isso é disponibilizada, no diretório APIs, a ClientAPI32Dbg.dll e o

DBGServer. A ClientAPI32Dbg.dll deve ser acessada no lugar da ClientAPI32.dll somente

quando estiver testando os acessos ao NeoKey e se precisar “debugar” seu aplicativo e

NUNCA deve ser distribuída para seu clientes.

A ClientAPI possui três grupos de funções configuradas de modo a facilitar a integração do seu

aplicativo e para cada modo há um grupo diferente de Exemplos:

a) Função única e diversos parâmetros (função NeoKeyCall)

b) Múltiplas funções e diversos parâmetros (funções –NeoKey_Login, NeoKey_Write,

NeoKey_x..)

c) Função Única e parâmetro único (função N_UN) (em breve)

Retorno

(inteiro) Ambas as funções retornam um inteiro informando se o comando foi realizado

com sucesso com o valor “0” zero ou um valor negativo para erro. Ver Tabela 1. (Erros).

Tabela 1 (Erros na ClientAPI)

Descrição Erro

Erro de leitura no NeoKey -1

Erro na gravação no NeoKey -2

Erro interno no NeoKey -4

NeoKey não encontrado -9

Possíveis causas para os erros acima: Os erros -1 e -2 ocorrem, pois os parâmetros iniciais de criptografia de acesso ao NeoKey não foram adequadamente inicializados ou foram corrompidos e por isso ao tentar fazer qualquer acesso no NeoKey o mesmo não consegue decifrar os comandos causando estes erros. Verifique se o projeto foi gravado corretamente. Verifique se está “logado” no NeoKey. O desafio está correto?

26


O NeoKey está conectado? O Led (luz) do NeoKey está aceso? Caso não esteja o NeoKey pode ter sido danificado ou o computador não o reconheceu. Tente reconectar o NeoKey novamente. Verifique se a porta USB está funcionando corretamente, com um mouse ou teclado USB.

Re-entrada de função -29

Parâmetro menor que o esperado -41

Função inválida -42

Possíveis causas para os erros acima: Verifique em nossos exemplos e manuais como são feitas as chamadas para cada função. Provavelmente é esperado um tipo de parâmetro e está sendo enviado um com a característica incorreta, como por exemplo, tamanho, verifique se não preencheu um ponteiro com Zeros, onde é esperado uma string e o tamanho informado para o ponteiro não corresponde ao esperado ou algum parâmetro de função não suportado foi passado.

Sistema básico não encontrado -43

Possíveis causas para os erro acima: Não foram encontradas APIs do sistema operacional que são necessárias para o funcionamento do produto, provavelmente será necessário reinstalar o sistema operacional.

NeoKey Bloqueado -44

Possíveis causas para o erro acima: O NeoKey foi bloqueado por mais de 10 tentativas de login com senha/desafio errados, para desbloquear será necessário regravar o projeto.

NeoKey inválido para uso em rede -45

Possíveis causas para o erro acima: Este é um NeoKey sem o recurso para funcionar em rede, será necessário comprar um NeoKey + Net

Função não suportada -46

Está função não é suportada no modo em que está sendo operada

A licença do NeoKey não pode ser compartilhada por múltiplos aplicativos -47

Servidor de Debug com falha -301

Comando de Debug não enviado -302

Tráfego de Debug violado -303

Dados no Debug inválidos -304

Possíveis causas para os erros acima: O sistema de debug não está funcionando adequadamente, verifique se há

27


alguma atualização disponível junto ao suporte técnico.

CPC Inválido -430

Não foi possível criar CDC -440

Arquivo de update não encontrado -450

Possíveis causas para os erros acima: Verifique se os dados utilizados para a atualização estão incorretos, verifique se tem permissão de gravação na pasta onde está a CliantAPI, verifique a procedência do arquivo CPC, se o Master utilizado para gerar o CPC é o mesmo que criou o projeto gravado, se está corrompido o arquivo ou se o CPC corresponde àquele dispositivo.

Servidor de rede não encontrado -1001

Comando de rede não enviado -1002

Tráfego bloqueado -1003

Dados corrompidos -1004

Possíveis causas para os erros acima: Verifique se o NeoKeyNetService está ativo na lista de processos de seu servidor, ele é necessário somente se o acesso for realizado através da rede, com o NeoKey + Net. Caso o acesso tenha sido realizado pelo tipo 0 local ou rede, interprete estes erros como NeoKey não encontrado. Caso o NeoKeyNetService esteja sendo executado, verifique se há algum firewall impedindo que os pacotes trafeguem entre os computadores, realize um comando ping do cliente para o servidor para ver se a rede está funcionando, caso tenha mais de uma placa de rede lembre-se de verificar as opções no arquivo de configuração.

Licença expirada por data -2000

Licença expirada por número de execuções -2001

Possíveis causas para os erros acima: A licença expirou, verifique a licença em seu projeto e observe os parâmetros de expiração por data, o erro ocorre quando a data configurada está inferior a data corrente ou o número de execuções chegou até Zero.

Data do sistema está inválida -2002

Possíveis causas para os erros acima: A data configurada internamente no NeoKey não corresponde a vigente pelo sistema operacional do cliente, verifique a data do sistema operacional do cliente, corrige-a e se o erro persistir atualize o NeoKey remotamente, como uma nova data de expiração, para corrigir a data do sistema interno.

NeoKey indisponível -2100

Possíveis causas para o erro acima:

28


O NeoKey não pode ser acessado, reconecte-o ao computador.

Necessário fazer Login -2103

Possíveis causas para o erro acima: Para executar algumas funções é necessário realizar o login primeiramente.

Atingido Limite de usuários de rede -2110

Possíveis causas para o erro acima: O número máximo de usuário em de rede para aquela licença foi atingido, verifique a quantidade definida em seu projeto.

Somente uma Instância por IP permitida -2120

Possíveis causas para o erro acima: O número máximo de instancias em de rede para aquele IP atingido, verifique esta opções em seu projeto.

Necessário fazer Logout -2160

Possíveis causas para o erro acima: Para executar algumas funções é necessário realizar o logout primeiramente.

Licença indisponível -2300

Possíveis causas para o erro acima: A licença que está tentando acessar está desabilitada, verifique em seu projeto.

Parâmetro Inválido -2310

Possíveis causas para os erros acima: Verifique em nossos exemplos e manuais como são feitas as chamadas para cada função. Provavelmente é esperado um tipo de parâmetro e está sendo enviado um com a característica incorreta, como por exemplo, tamanho, verifique que não preencheu um ponteiro com Zeros, onde é esperado uma string ou o tamanho informado para o ponteiro não corresponde ao esperado.

OTP Inválido -2801

Necessário realizar Sincronismo OTP -2802

Possíveis causas para os erros acima: A senha OTP que está usando não está correta, verifique se as chaves K1 e K2 estão corretas, elas são geradas na pasta OTPKEYS toda vez que o projeto é salvo. Antes de iniciar a validação OTP função (51), é necessário realizar a função de sincronismo (50).

Web update não está respondendo corretamente. -5460

Web update está bloqueado. -5461

Web update, a conexão com o computador local não pode ser inicializada. -5462

29


Possíveis causas para os erros acima: Há algum problema de conexão com a web ou nossos servidores estão indisponíveis, verfique se nosso site www.neoprot.com.br pode ser acessado e se há conexão para internet.

Web update, erro de sintaxe. -5464


Web update, usuário master não autorizado. -5465

Possíveis causas para o erro acima: Para usar o serviço é necessário se cadastrar, solicite junto ao suporte o seu cadastro neste serviço.

Web update, erro geral no serviço. -5466


Web update, limite máximo permitido de NeoKeys na WEB atingido. -5467

Possíveis causas para o erro acima: Verifique junto ao suporte qual é a quantidade máxima de NeoKeys permitida e cadastrada para você no serviço de Web update.

NeoKeyCall

A API possui uma função de acesso chamada “NeoKeyCall” que realiza todas as operações e

comandos disponíveis pelo hardware.

Protótipo da função:

int APIENTRY NeoKeyCall (

int cmd, // Comando ( veja a tabela de comandos abaixo)

LPSTR param1, // Parâmetro 1 (Ponteiro BYTE)

int p1, //Tamanho do Parâmetro 1 ou parâmetro auxiliar

LPSTR param2, //Tamanho do Parâmetro 2 (Ponteiro BYTE)


LPSTR param3, //Tamanho do Parâmetro 3 (Ponteiro BYTE)


struct LicenseParameters * Licparam // Estrutura de licenças do NeoKey.);


30


Parâmetros:

int cmd

(Inteiro) É o comando a ser realizado pelo NeoKey, veja a Tabela 2. (Comandos)

Tabela 2 (Comandos)

Descrição Comando

Login 1

Gravar na memória (DWORD) 2

Ler da memória (DWORD) 3

Criptografar 4

Descriptografar 5

Ler a licença 7

Gravar na memória (WORD) 8

Ler da memória (WORD) 9

Ler ID do Hardware 10

Ler uma página da memória 11

Gravar uma página da memória 12

Buscar próximo NeoKey 14

Reiniciar busca 15

Logout 16

Ler o código de atualização (CDC) 31

Aplicar atualização via código (CPC) 32

Aplicar atualização via arquivo 33

Sicronizar OTP (SincOTP) 50

Login OTP 51

SetSinc 53

LPSTR param1, LPSTR param2, LPSTR param3

(Ponteiro de BYTES) São parâmetros usados pelos comandos.

int p1, int p2, int p3

(inteiro) Informa o tamanho do ponteiro de bytes ou é um parâmetro auxiliar do

comando.

struct LicenseParameters * Licparam

É o ponteiro da estrutura utilizada pela API para informações relativas a licença.

typedef struct LicenseParameters

{ unsigned char Enable; // Se a licença está habilitada

31


unsigned char SingleInstance; //Se somente uma instância do aplicativo por IP na rede

unsigned char Netusers; // Usuários de Rede

unsigned char ExpireDate[8]; //Data de expiração

unsigned char Counter[2]; // Número de execuções de execuções

unsigned char ID; // Identificação da licença (0 até 63)

unsigned char Reserved[2]; // Reservado para o futuro.

}LicenseParameters;

Descrição dos Comandos

Login - cmd = 1

Este dever ser o primeiro comando a ser executado, para que os outros comandos possam

funcionar. (Veja também a opção mais segura – LoginOTP).

O comando (1) login, é utilizado para encontrar o NeoKey conectado e responsável pelo “login”

da licença, possui como premissa um esquema de desafio-resposta (challenge-response) que

é configurado no seu projeto através do DevTool, ele utiliza somente um parâmetro (param1)

com o desafio/Senha (challenge) e neste mesmo parâmetro é retornado uma resposta

(response), quando o hardware é conectado.

O tamanho do desafio e da resposta é 16 Bytes, podendo este ser qualquer caractere.

O NeoKey possui um mecanismo de segurança que bloqueia sua utilização caso seja feito o

login com o Challenge (Desafio/Senha) errado, por mais de 10 vezes. Para desbloquear será

necessário gravar novamente o projeto no NeoKey via o DevTool.

Na estrutura de licença (LicenseParameters) deve ser informado na variável ID o número da

licença que vai ser feito o Login e na variável Enable o modo de acesso ao Hardware (0,1 ou 2)

e que informa após o acesso ao NeoKey, no caso (Enable=0), se o acesso foi local ou pela

rede, sendo que:

LicenseParameters.ID=0 // Ou qualquer número de 0 até 63 LicenseParameters.Enable = 0 // Local ou Rede LicenseParameters.Enable = 1 //Somente Local LicenseParameters.Enable = 2 //Somente Rede Exemplo:

LicenseParameters.ID=0 LicenseParameters.Enable=0 Senha = “1234567890123456”

32


Int ret =NeoKeyCall (1, senha, senha.Length, NULL, 0, NULL, 0, LicenseParameters)

If ret = 0 Sucesso ou If ret <> 0 Erro

Print (senha) Resposta = “abcdefghijlmnopq” e LicenseParameters.Enable=1 (acesso local)

Gravar na Memória (DWORD) - cmd = 2

O comando (2) grava dados na memória do NeoKey, que possui uma capacidade total 1K

DOUBLE WORDS, 4096 BYTES, endereçados de 0 a 1023. Lembrando que uma DOUBLE

WORD (DWORD) possui 4 bytes, totalizando então 4KBytes disponíveis para gravação no

NeoKey.

Exemplo:

Queremos gravar a informação: “1234” que contém 4 bytes ou 1 DWORD no endereço da

memória

Meudado=“1234”

Endereço=0

Int ret =NeoKeyCall (2, Meudado, Endereço, NULL, 0, NULL, 0, NULL)


Ler da memória (DWORD) - cmd = 3

O comando (3) lê da memória uma DWORD.

Exemplo:

Queremos ler a informação, no endereço 0 da memória.

Meudado=“XXXX”

Endereço=0



Na variável meudado é retornado o valor lido da memória.

Print (Meudado) >“1234”

Criptografar - cmd = 4

O comando (4) criptografar permite cifrar/criptografar uma informação.

33


O NeoKey, possui um mecanismo de criptografia AES, com chave de 256 bits, que é

considerado um dos mais fortes mecanismos existentes no mercado hoje e sua chave de

criptografia é definida no projeto, através do DevTool.

Esta função pode ser usada, por exemplo, para criptografar dados sigilosos em bases de

dados, arquivos de configuração, etc.

O AES criptografa informações formatadas com tamanho múltiplo de 16 bytes, sendo

importante dimensionar a variável de acordo com essa premissa antes de acessar o comando.

Exemplo:

Queremos criptografar a informação: “1234567890123456” que contém 16 bytes

Meudado=“1234567890123456”

tamanho=16

Int ret =NeoKeyCall (4, Meudado, tamanho, NULL, 0, NULL, 0, NULL)


Na variável meudado é retornado o valor criptografado.

Print ( Meudado) > “:/<)*t#Fj!xB{iMn”

Descriptografar - cmd = 5

O comando (5) descriptografar, permite decifrar/descriptografar uma informação.

Esta função pode ser usada, por exemplo, para descriptografar dados sigilosos em bases de

dados, arquivos de configuração, etc, que foram criptografados pelo comando 4.

O AES descriptografa informações formatadas com tamanho múltiplo de 16 bytes, sendo


Exemplo:

Queremos criptografar a informação: “:/<)*t#Fj!xB{iMn” que contém 16 bytes e retornado o

comando (4)

Meudado=“:/<)*t#Fj!xB{iMn”

tamanho=16

Int ret =NeoKeyCall (5, Meudado, tamanho, NULL, 0, NULL, 0, NULL)


Na variável meudado é retornado o valor descriptografado.

34


Print (Meudado) > “1234567890123456”

Ler a licença - cmd = 7

O comando (7) lê as informações relativas à licença que está “logado”.

Exemplo:

Queremos ler o estado da licença ID = 0.

LicenseParameters=0

Int ret =NeoKeyCall (7, NULL, 0, NULL, 0, NULL, 0, LicenseParameters)


Na variável LicenseParameters é retornado o valor lido da licença.

Licençahabilitada=LicenseParameters.Enable

Data= LicenseParameters.ExpireDate

Contador = LicenseParameters.counter (número de execuções)

Usuárioderede=LicenseParameters.Netusers

InstanciaUnica= LicenseParameters.SingleInstance

Gravar na Memória (WORD) - cmd = 8

O comando (8) gravar na memória uma WORD, ou seja, é utilizado para gravar dados na

memória do NeoKey, e este possui um total de 2K WORDS, endereçados de 0 a 2047.

Lembrando que uma WORD (DWORD) possui 2 bytes, totalizando então 4KBytes disponíveis

para gravação no NeoKey.

Exemplo:

Queremos gravar a informação: “12” que contém 2 bytes ou 1 WORD no endereço 0 da página

0 da memória

Meudado=“12”

Endereço=0



35


Ler da memória (WORD) - cmd = 9

O comando (9) lê da memória uma WORD.

Exemplo:

Queremos ler a informação, no endereço 0 da memória.

Meudado=“XX”

Endereço=0




Print ( Meudado) >“12”

Ler ID do Hardware - cmd = 10

O comando (10) lê o HardwareID, que é o número de identificação exclusivo daquele NeoKey,

este número é único, ou seja cada NeoKey possui um HardwareID diferente do outro.

Este ID, possui uma informação de 8 Bytes.

Exemplo:

HardwareID=“XXXXXXXX”

tamanho=8

Int ret =NeoKeyCall (10, HardwareID, tamanho, NULL, 0, NULL, 0, NULL)



Print (HardwareID) > 25700001

Ler uma página da memória - cmd = 11

O comando (11) lê uma página/bloco inteiro da memória, permitindo uma leitura mais rápida da

memória e lendo de uma só vez 1024 Bytes.

Exemplo:

36


Queremos ler a página/bloco 0 da memória.

Meudado=“XX...X” //Esta variável deve ter 1024 bytes de tamanho, caso contrário pode causar

uma corrupção da variável

Pagina/Bloco=0,1,2 ou 3

Int ret =NeoKeyCall (11, Meudado, 0, NULL, Pagina, NULL, 0, NULL)



Print ( Meudado) >“12….”

Gravar uma página na memória - cmd = 12

O comando (12) grava uma página/bloco inteiro na memória, permite uma gravação mais

rápida da memória, gravando de uma só vez 1024 Bytes.

Exemplo:

Queremos gravar a página/bloco 0 da memória, com o dado “ABCD...”, podendo ser qualquer

valor.

Meudado=”ABCDABCD...A” //Esta variável deve ter 1024 bytes de tamanho, caso contrário

pode causar um corrupção da variável

Pagina/Bloco=0,1,2 ou 3

Int ret =NeoKeyCall (12, Meudado, 0, NULL, Pagina, NULL, 0, NULL)


Buscar próximo NeoKey - cmd = 14

O comando (14) permite buscar outro NeoKey conectado no PC (para acessos via rede este

comando é ignorado).

Neste comando, quando já tiver sido feito o Login em um NeoKey, deverá ser realizado um

Logout deste primeiro, então execute o comando (14) e finalmente um novo Login deve ser

realizado no segundo NeoKey para ter acesso aos outros comandos.

Exemplo:

Int ret = NeoKeyCall (14, NULL, 0, NULL, 0, NULL, 0, NULL)


37


Reiniciar busca - cmd = 15

O comando (15) permite reiniciar a busca de NeoKey conectado no PC, por exemplo quando o

comando 14 é executado, e você gostaria de acessar o primeiro NeoKey novamente.

Neste comando quando já tiver sido feito o Login em um outro NeoKey, deverá ser realizado

um Logout deste segundo, então execute o comando (15) e finalmente um novo Login deve ser

realizado no primeiro NeoKey para ter acesso aos outros comandos.

Exemplo:



Logout - cmd = 16

O comando (16) finaliza os acessos a uma licença no NeoKey, impedindo que qualquer

comando possa ser executado.

Exemplo:



Ler o código de atualização (CDC) - cmd = 31

O comando (31) instrui o NeoKey a gerar um CDC (código do cliente) que é o código gerado

para realizar uma atualização, sem este código não é possível atualizar os dados do NeoKey.

O CDC é um conjunto de 32 bytes, único para cada processo de atualização e deve ser

enviado ao desenvolvedor do software, para que este, através do DevTool gere o CPC (código

para o cliente) que contém as informações de atualização.

Exemplo:

CDC=”XXXX…X” //Esta variável deve ter 32 bytes de tamanho, caso contrário pode causar

uma corrupção da variável

Int ret =NeoKeyCall (31, CDC, 32, NULL, 0, NULL, 0, NULL)


Print(CDC)

38


Aplicar atualização via código (CPC) - cmd = 32

O comando (32) instrui o NeoKey, através de um CPC (código para o cliente), a atualizar dados

relativos exclusivamente a uma licença, permitindo atualizar o número de usuários de rede,

número de execuções e data de expiração, remotamente.

O CPC é um conjunto de 32 bytes, único para cada processo de atualização e deve ser

enviado ao cliente do desenvolvedor do software.

Exemplo:

CPC=”12345678901234567890123456789012” //Esta variável deve ter 32 bytes de tamanho,

caso contrário pode causar uma corrupção da variável

Int ret =NeoKeyCall (32, CPC, 32, NULL, 0, NULL, 0, NULL)


Aplicar atualização via arquivo (CPC) - cmd = 33

O comando (33) instrui o NeoKey, através de um arquivo .CPC (código para o cliente), a

atualizar todos os dados gravados no hardware, permitindo atualizar o desafio-resposta, chave

de criptografia, licenças e a memória, remotamente.

O arquivo .CPC deve ser usado com cuidado, pois ele permite a atualização sem associar a

um CDC ou a um HardwareID específico.

Exemplo:

ArquivoCPC=”c:\atualiza.cpc” //Esta variável deve ter no máximo 255 bytes de tamanho, caso

contrário pode causar uma corrupção da variável

Tamanho=15

Int ret =NeoKeyCall (33, ArquivoCPC, Tamanho, NULL, 0, NULL, 0, NULL)


SetSinc - cmd = 53

Este comando dever ser executado antes de acessar a função (50) SincOTP para que seja

criado o mecanismo de sincronização seguro entre o Hardware e seu programa, você deve

criar um número aleatório e enviar para o dispositivo, que retorna de volta um código que você

deve validar, e se não corresponder ao valor esperado deverá terminar a validação. Este

número aleatório pode ser gerado como lhe for conveniente, procure gerá-lo da forma mais

segura possível.

A validação deve ocorrer da seguinte forma.

39


1. ArrayRandom = Gerar um array de 8 bytes – randômico

2. Chamar a função 53 e enviar os dados randômicos ao Hardware

3. Chamar a função 50 SincOTP

4. Comparar os 8 primeiros bytes da resposta recebida do Hardware, sendo que

a. Resposta do Hardware = HASH_SHA1(K1(20 bytes) + ArrayRandom(8 bytes))

5. Se a resposta não for correta deve-se parar o programa.

SincOTP - cmd = 50

Este dever ser o comando a ser executado, antes de acessar a função (51) LoginOTP para que

seja criado o mecanismo de sincronização entre a API, o Hardware e seu programa, para

realizar uma autenticação segura.

Na estrutura de licença (LicenseParameters ) deve ser informado o modo de acesso ao

Hardware, na variável Enable sendo:

LicenseParameters.Enable = 0 // Local ou Rede LicenseParameters.Enable = 1 //Somente Local LicenseParameters.Enable = 2 //Somente Rede Exemplo:

LicenseParameters.Enable = 0

SINC = “xxxxxxxxxxx”

Int ret =NeoKeyCall (50, SINC, 8, NULL, 0, NULL, 0, dev)


LoginOTP - cmd = 51


funcionar (exceto o SincOTP).

O comando (51) LoginOTP, é utilizado para encontrar o NeoKey conectado e responsável pelo

“login” da licença, possui como premissa um esquema de desafio-resposta (challenge-

response) baseado em uma senha que é modificada para cada acesso, conhecido como OTP

(ONE TIME PASSWORD), incrementando muito a fator segurança. O OTP possui duas chaves

K1 e K2, que são derivadas do desafio-resposta configurado no seu projeto, através do

DevTool, e para calculá-lo será necessário chamar as funções SincOTP(50) e SetSinc(53) para

obter os dados de sincronização.

Esta função utiliza somente um parâmetro (param1) com o desafio/Senha (challenge) e neste

mesmo parâmetro retorna uma resposta (response), quando o hardware está conectado.

40


O desafio deve ser calculado da seguinte forma (consulte os exemplos para entender melhor):

OTP=HASH_SHA1(SINC + K1)

O tamanho do desafio e da resposta é 16 Bytes, sendo ignorado os últimos 4 bytes gerados do

HASH, e podendo este ser qualquer caractere.

Para verificar que a resposta está correta, devemos verificar da seguinte forma:

OTP_Check=HASH_SHA1(SINC + K2)

Se (OTP_Check = Response-retornado da chamada da função (51) (param1)) então está tudo

OK.

K1 e K2 são gerados em arquivos para serem usados pelos exemplos, cada vez que um

projeto é salvo, e ficam armazenados no diretório (OTPKEYS). (Os exemplos devem ser

“recompilados”).

O NeoKey possui um mecanismo de segurança que bloqueia sua utilização casos seja feito o

login com o Challenge(Desafio/Senha) errado, por mais de 10 vezes. Para desbloquear será


Na estrutura de licença (LicenseParameters ) deve ser informado o número da licença, que vai

ser feito o Login, na variável ID e o modo de acesso ao Hardware, na variável Enable sendo:

LicenseParameters.ID=0 // Ou qualquer número de 0 até 63

LicenseParameters.Enable = 0 // Local ou Rede LicenseParameters.Enable = 1 //Somente Local LicenseParameters.Enable = 2 //Somente Rede Exemplo:

LicenseParameters.ID=0

LicenseParameters.Enable = 0

Senha = “1234567890123456”

Int ret =NeoKeyCall (51, senha, senha.Length, NULL, 0, NULL, 0, dev)


Funções NeoKey_

NeoKey_Login OU NeoKey_LoginOTP

Protótipo:

int NeoKey_Login(unsigned char *message, unsigned int size,unsigned int licenseID, unsigned

int Type,unsigned char *HardwareID)

41


OU

int NeoKey_LoginOTP(unsigned char *message, unsigned int size,unsigned int licenseID,

unsigned int Type,unsigned char *HardwareID)


funcionar.

Esta função é utilizada para encontrar o NeoKey conectado e é responsável pelo “login” da

licença, possui como premissa um esquema de desafio-resposta (challenge-response) que é

configurado no seu projeto através do DevTool, ele utiliza o parâmetro (message) com o

desafio/Senha (challenge) e neste mesmo parâmetro é retornado uma resposta (response),

quando o hardware é conectado, no parâmetro size deve ser informado o tamanho da senha

(16), no parâmetro licenseID deve ser informado o número de licença que será utilizada o valor

deve ser (0 até 63), no parâmetro Type deve ser informado o modo de acesso à chave sendo

(0 = Local e rede, 1 = somente local e 2 =somente rede), no parâmetro HardwareID é retornado

o número de identificação do Hardware(8 Bytes), antes de chamar a função lembre-se de

dimensionar o parâmetro HardwareID com 8 bytes, para evitar corrupção da memória.


O NeoKey LoginOTP, é baseado em uma senha que é modificada para cada acesso,

conhecido como OTP (ONE TIME PASSWORD), incrementando muito a fator segurança. O

OTP possui duas chaves K1 e K2, que são derivadas do desafio-resposta configurado no seu

projeto, através do DevTool, e para calculá-lo será necessário, antes, chamar a função

NeoKey_SincOTP para obter os dados de sincronização.

O desafio deve ser calculado da seguinte forma (consulte os exemplos para entender melhor):

OTP=HASH_SHA1(SINC + K1)

O tamanho do desafio e da resposta é 16 Bytes, sendo ignorado os últimos 4 bytes gerados do

HASH, e podendo este ser qualquer caractere.

Para verificar que a resposta está correta, devemos verificar da seguinte forma:

OTP_Check=HASH_SHA1(SINC + K2)

Se (OTP_Check = Response-retornado da chamada da função (51) (param1)) então está tudo

OK.

K1 e K2 são gerados em arquivos para serem usados pelos exemplos, cada vez que um

projeto é salvo, e ficam armazenados no diretório (OTPKEYS). (Os exemplos devem ser

“recompilados”).


login com o Challenge(Desafio/Senha) errado por mais de 10 vezes. Para desbloquear será


42


Exemplo:

Senha = “1234567890123456”

HardwareID=”xxxxxxxx”

Int ret = NeoKey_Login(Senha, 16,0, 0, HardwareID)


Print (senha) Resposta = “abcdefghijlmnopq”

Print (HardwareID) Resposta = “00000001”

NeoKey_SincOTP

int NeoKey_SincOTP(unsigned char *Sinc, unsigned int Type)

Este dever ser o comando a ser executado, antes de acessar a NeoKey_LoginOTP para que

seja criado o mecanismo de sincronização entre a API, o Hardware e seu programa, para

realizar uma autenticação segura baseada em OTP.

Em “Type” deve ser informado o modo de acesso à chave, sendo (0 = Local e rede, 1 = somente local e 2 =somente rede) Exemplo:

Type = 0

SINC = “xxxxxxxxxxx”

Int ret =NeoKeyCall (SINC,Type)


NeoKey_Logout

int NeoKey_Logout(void)

Finaliza os acessos a uma licença no NeoKey, impedindo que qualquer comando possa ser

executado.

Exemplo:

Int ret =NeoKey_Logout ()


NeoKey_Write

int NeoKey_Write(unsigned char *message, unsigned int size, unsigned int offset)

É utilizado para gravar dados na memória do NeoKey, no parâmetro message devem ser

passados os dados a serem gravados, lembrando que, esta informação de ter um tamanho

43


múltiplo de 4, ou seja 4,8,16,20,etc bytes, o parâmetro “size” é o tamanho de dados, o

parâmetro offset é o endereço inicial onde serão gravados os dados.

O NeoKey possui um total 1K DOUBLE WORDS, endereçados de 0 a 1023.

Exemplo:

dados = “1234567890123456”

Int ret = NeoKey_Write(dados, 16,0)


NeoKey_Read

int NeoKey_Read(unsigned char *message, unsigned int size, unsigned int offset)

É utilizado para ler dados da memória do NeoKey, no parâmetro message deve estar

dimensionado de acordo com os dados a serem lidos, lembrando que, esta informação de ter

um tamanho múltiplo de 4, ou seja 4,8,16,20,etc bytes, no parâmetro ”size” é o tamanho de

dados, o parâmetro offset é o endereço inicial de onde serão lidos os dados.

O NeoKey possui um total 1K DOUBLE WORDS, endereçados de 0 a 1023.

Exemplo:

dados = “xxxxxxxxxxxxxxxx”

Int ret = NeoKey_Read(dados, 16,0)


Print (dados) Resposta = “1234567890123456”

NeoKey_Login_Next

int APIENTRY NeoKey_Login_Next(unsigned char *message,unsigned int size, unsigned int

licenseID, unsigned int Type,unsigned char *HardwareID)

Esta função é utilizada para encontrar outro (próximo) NeoKey conectado, (para acessos via

rede este comando é ignorado), quando já há um primeiro conectado e assim como a função

NeoKey_Login é responsável pelo “login” da licença, possui como premissa um esquema de

desafio-resposta (challenge-response) que é configurado no seu projeto através do DevTool,

ele utiliza o parâmetro (message) com o desafio/Senha (challenge) e neste mesmo parâmetro é

retornado uma resposta (response), quando o hardware é conectado, no parâmetro size deve

ser informado o tamanho da senha (16); no parâmetro licenseID de ser informado o número de

licença que será utilizada, o valor deve ser (0 até 63); no parâmetro Type deve ser informado o

modo de acesso à chave sendo (0 = Local e rede, 1 = somente local e 2 =somente rede); no

parâmetro HardwareID é retornado o número de identificação do Hardware(8 Bytes), antes de

chamar a função lembre-se de dimensionar o parâmetro HardwareID com 8 bytes, para evitar

corrupção da memória.

44




login com o Challenge(Desafio/Senha) errado, por mais de 10 vezes. Para desbloquear será


Exemplo:

Senha = “1234567890123456”

HardwareID=”xxxxxxxx”

Int ret = NeoKey_Login_Next(Senha, 16,0, 0, HardwareID)


Print (senha) Resposta = “abcdefghijlmnopq”

Print (HardwareID) Resposta = “00000002”

NeoKey_Crypt

int NeoKey_Crypt(unsigned char *message, unsigned int size)

Permite cifrar/criptografar uma informação.

O NeoKey, possui um mecanismo de criptografia AES, com chave de 256 bits, que é

considerado um dos mais fortes mecanismos existentes no mercado hoje e sua chave de

criptografia é definida no projeto, através do DevTool.

Esta função pode ser usada, por exemplo, para criptografar dados sigilosos em bases de

dados, arquivos de configuração, etc.



Exemplo:

Queremos criptografar a informação: “1234567890123456” que contém 16 bytes

Meudado=“1234567890123456”

tamanho=16

Int ret = NeoKey_Crypt (Meudado, tamanho)


Na variável meudado é retornado o valor criptografado.

45


Print ( Meudado) > “:/<)*t#Fj!xB{iMn”

NeoKey_Decrypt

int NeoKey_Decrypt(unsigned char *message, unsigned int size)

Permite decifrar/descriptografar uma informação.



Exemplo:

Queremos criptografar a informação: “:/<)*t#Fj!xB{iMn”que contém 16 bytes que foi

criptografada pelo NeoKey.

Meudado=“:/<)*t#Fj!xB{iMn”

tamanho=16

Int ret = NeoKey_Decrypt (Meudado, tamanho)


Na variável meudado é retornado o valor descriptografado.

Print ( Meudado) > =“1234567890123456”

NeoKey_GetLicense

int APIENTRY NeoKey_GetLicense(

unsigned char ID, //IN

unsigned char * Enable,//OUT

unsigned char * SingleInstance,//OUT

unsigned char * Netusers,//OUT

unsigned char * ExpireDate,//OUT

unsigned int * Counter//OUT

)

Esta função lê informações relativas a uma licença.

Exemplo:

Queremos ler o estado da licença ID = 0.

ID=0

46


Enable=x

SingleInstance=x

Netusers=x

ExpireDate=”xxxxxxxx” (8 bytes)

Counter=x

Int ret = NeoKey_GetLicense (ID, Enable, SingleInstance, Netusers, ExpireDate, Counter)


Em cada parâmetro é retornado o valor lido da licença.

Em ExpireDate, é retornado o dia da expiração no formato (dd/mm/yy).

ClientAPI – Arquivo de Configuração

A ClientAPI, permite ao desenvolvedor parametrizar o comportamento da API, através de um

arquivo de configuração que deverá estar no mesmo diretório que ela, e com o mesmo nome,

mudando somente a extensão para .ini, não sendo sua presença obrigatória mesmo para

acesso via Rede e sendo opcional todos os itens descritos abaixo.

[SETTINGS]

port=30005

//indica a porta a ser usada para a comunicação via REDE

broadcast_enable=1

//Permite a localização automática do servidor de rede em que o NeoKey está conectado.

net_enable=1

//Permite acessar o NeoKey pela Rede

log=1

// Habilita o LOG dos acessos

[SERVER]

net_timeout=1000

//Permite definir o valor do TIMEOUT (em mili segundos) para acessos na rede

name_or_ip=192.168.1.101

//Informa o IP ou nome do servidor de rede em que o NeoKey será conectado.

47


[LOCAL]

Ip_ok=192.168.1.101

//Quando há mais de uma de rede no PC, deve-se informar por qual rede os dados vão

trafegar.

[UPDATE]

alarm_message_counter= Seu sistema está quase expirando. Número de execuções=

alarm_message_days = Faltam alguns dias para expirar sua licença. Número de dias=

//Aqui definimos a mensagem ao usuário do NeoKey para os controles de expiração.

alarm=1

//Aqui habilitamos se a mensagem de será apresentada

counter=100

//Permite definir a partir de qual valor de contador do número de execuções as mensagens de

atualização serão apresentadas, caso não seja especificado o valor padrão é quando o

contador for igual a 20.

days=10

//Permite definir a partir de quantos dias antes de expirar o NeoKey as mensagens de

atualização serão apresentadas, caso não seja especificado o valor padrão é 7 dias.

[WEBUPDATE]

enable=1

//Habilita a atualização do NeoKey pela internet usando o NeoKey NOW, (NeoKey Over The

Web)

alarm_message=Erro ao realizar Webupdate

//Aqui definimos a mensagem de erro caso o NeoKey NOW não possa ser acessado.

alarm=1

//Aqui habilitamos se a mensagem de erro será apresentada caso o NeoKey NOW não possa

ser acessado.

counter=100

48


//Permite definir a partir de qual valor de contador do número de execuções as checagens de

atualização automáticas serão ativadas.

days=10

//Permite definir a partir de quantos dias antes de expirar o NeoKey, as checagens de

atualização automáticas serão ativadas.

49


NeoKeyNetService

O NeoKeyNetService é o software responsável por realizar os acessos ao NeoKey através da

Rede.

Quando uma aplicação faz o Login na ClientAPI, se e os recursos de rede estiverem

habilitados, tenta localizar automaticamente um servidor na Rede onde esteja sendo

executado o NeoKeyNetService, para então iniciar os acessos ao NeoKey+Net através da Rede.

O NeoKeyNetService pode ser executado a partir de qualquer pasta como uma aplicação

normal bastando um duplo clique sobre ele ou ainda instalá-lo como um serviço.

Para mostrar todas as mensagens inclusive o log, execute o comando: NeoKeyNetService -d

Para instalar o serviço do NeoKeyNetService execute o comando: NeoKeyNetService -i

Para desinstalar o serviço do NeoKeyNetService execute o comando: NeoKeyNetService -u

Para fechar/terminar o aplicativo utilize a tecla “t”.

Através do log é possível verificar quais máquinas estão acessando o Serviço e estado das

licenças.

Ainda é possível visualizar a utilização das licenças via browser: http://<ip_do_servidor>:porta,

ex: http://192.168.0.10:30005

NeoKeyNetService – Arquivo de Configuração

A NeoKeyNetService, permite ao desenvolvedor parametrizar seu comportamento, através de

um arquivo de configuração que deverá estar no mesmo diretório que ele, e com o mesmo

nome, mudando somente a extensão para .ini, não sendo sua presença obrigatória e sendo

opcional todos os itens descritos abaixo.

[SETTINGS]

port=30005 //indica a porta a ser usada para a comunicação via REDE

log=1 // Habilita o LOG dos acessos

[LOCAL]

ip_ok=192.168.1.101 //Quando há mais de uma rede no PC, podemos informar por qual rede

os dados vão trafegar.

É possível ainda usar o TELNET do Windows ou Linux (verifique como habilitar ou instalar no

manual do seu sistema operacional) ou o PUTTY, programa gratuito que pode ser encontrado

na internet, para obter informações e visualizar o estado das licenças no NeoKeyNetService

através da rede, para isto, você deve executar o putty.exe e abrir uma conexão Telnet para o IP

50


onde está instalado o NeoKeyNetService usando a porta ex: 30005, logo que se conectar,

digite qualquer tecla e deverá aparecer uma mensagem “#ServerReady” e para iniciar a

visualização basta digitar no terminal o texto “cmd” [enter], neste instante será listada todas as

conexões por número de processo e IP e logo após os acessos que estão ocorrendo.

Ex: c:\>telnet 192.168.0.30 30005

[UPDATE]

alarm_message_counter= Seu sistema está quase expirando. Número de execuções=

alarm_message_days= Faltam alguns dias para expirar sua licença. Número de dias=

//Aqui definimos a mensagem ao usuário do NeoKey para os controles de expiração.

alarm=1

//Aqui habilitamos se a mensagem de será apresentada

counter=100

//Permite definir a partir de qual valor de contador do número de execuções, que as mensagens

de atualização serão apresentadas, caso não seja especificado o valor padrão é quando o

contador for igual a 20.

days=10

//Permite definir a partir de quantos dias antes de expirar o NeoKey as mensagens de

atualização serão apresentadas, caso não seja especificado o valor padrão é 7 dias.

[WEBUPDATE]

enable=1

//Habilita a atualização do NeoKey pela internet usando o NeoKey NOW , (NeoKey Over The

Web)

alarm_message=Erro ao realizar Webupdate

//Aqui definimos a mensagem de erro caso o NeoKey NOW não possa ser acessado.

alarm=1

//Aqui habilitamos se a mensagem de erro será apresentada caso o NeoKey NOW não possa

ser acessado.

counter=100

51


//Permite definir a partir de qual valor do contador de número de execuções, que as checagens

de atualização automáticas serão ativadas, caso não seja especificado o valor padrão é

quando o contador for igual a 20

days=10

//Permite definir a partir de quantos dias antes de expirar o NeoKey, as checagens de

atualização automáticas serão ativadas, caso não seja especificado o valor padrão é 7 dias.

sdk - neoprot.com.br · p | seguro, fácil e rápido. roteção e licenciamento no seu software....

Documents