Proteção e licenciamento
| Seguro, fácil e rápido.
SDK
no seu software.
Manual do Desenvolvedor v 2.0.4
NeoKey
NeoKey SDK versão 2.0.4
Í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 ......................................................................................................................... 33
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 ............................................................................................. 36
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_ .................................................................................................................................. 41
NeoKey_Login OU NeoKey_LoginOTP .............................................................................................. 41
NeoKey_SincOTP ............................................................................................................................... 42
NeoKey_Logout .................................................................................................................................. 42
NeoKey_Write ..................................................................................................................................... 43
NeoKey_Read ..................................................................................................................................... 43
NeoKey_Login_Next ........................................................................................................................... 43
NeoKey_Crypt ..................................................................................................................................... 44
NeoKey_Decrypt ................................................................................................................................. 45
2
NeoKey SDK versão 2.0.4
NeoKey_GetLicense ........................................................................................................................... 45
CLIENTAPI – ARQUIVO DE CONFIGURAÇÃO ................................................................................................ 46
NEOKEYNETSERVICE .............................................................................................................................. 49
NEOKEYNETSERVICE – ARQUIVO DE CONFIGURAÇÃO................................................................................. 49
3
NeoKey SDK versão 2.0.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
M
Memória ........................................................... 13
Mínimo Hardware Requerido ............................. 7
N
F
NeoKey .............................................................. 6
NeoKey Master ................................................ 22
NeoKey NOW .................................................. 24
NeoKey+Net ...................................................... 6
NeoKeyCall ...................................................... 29
NeoKeyNetService........................................... 48
NeoKeyNetService – Arquivo de Configuração
..................................................................... 48
Funções NeoKey .............................................. 40
P
G
Proteção Automática ....................................... 21
Gerar as APIs ................................................... 16
S
L
Salvar e Gravar ................................................ 14
Sistemas Operacionais Suportados .................. 7
D
Desafio-Reposta e Criptografia ........................ 11
DevTool .............................................................. 8
Licenças ........................................................... 11
LoginOTP .......................... 31, 38, 39, 40, 41, 42
4
NeoKey SDK versão 2.0.4
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
5
NeoKey SDK versão 2.0.4
NeoKey
Recursos
Driver Less
Memória 4 KBytes
Exemplos e APIs
Hardware ID
Criptografia AES256
Bloqueio de senha
Anti-Debug
64 licenças
Chave Master
Multi-thread
Atualização
Remota
NeoKey+Net
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
6
NeoKey SDK versão 2.0.4
operacional. A API deve fazer parte da instalação do seu aplicativo, sendo 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.
Consulte o capítulo do DevTool para maiores detalhes de como gerar a ClientAPI.
Consulte o capítulo da NeoKeyMaster para maiores detalhes sobre os recursos 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, 2003 ou 2008.
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/)"
"This product includes software developed by the OpenSSL Project for use in the OpenSSL
Toolkit. (http://www.openssl.org/)"
7
NeoKey SDK versão 2.0.4
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.
Criar um projeto
Gerar as APIs
Proteger seu Software
Defina o licenciamento
Gere as APIs e distribua
com o seu produto
Automático, selecione o
arquivo a ser protegido
Salve e grave o projeto
Teste o projeto gravado
Via API, consulte os
exemplos.
Tabela A (Erros no DevTool)
Descrição
Erro de leitura
Erro na gravação
Erro no Login
Erro no comando
Master não conectado
NeoKey não conectado
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.
Erro
-5001
-5002
-5003
-5004
-5006
-5007
8
NeoKey SDK versão 2.0.4
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
Os sistema operacional não está adequadamente
instalado e não será possível acessar o NeoKey.
Master sem previlégio
O Master que está usando está com privilégios de
acesso limitados, para realizar uma tarefa.
NeoKey inválido
O NeoKey não possui as características necessárias de
configuração para que este SDK e Master.
CDC inválido
Os dados enviados pelo cliente estão incorretos, tente
verificar junto ao cliente se ele antou corretamente.
MasterII não conectado
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
Erro ao gravar arquivo de Backup
Arquivo de atualização não encontrado
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.
Web update (NeoKey NOW) está bloqueado.
Web update, a conexão com o computador local não pode ser
inicializada.
-5008
-5009
-5010
-5025
-5026
-5101
-5300
-5450
-5460
-5461
-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.
9
NeoKey SDK versão 2.0.4
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
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.
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.
10
NeoKey SDK versão 2.0.4
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 desafioresposta e a chave de criptografia.
Licenças
Neste passo podemos configurar as características das licenças.
11
NeoKey SDK versão 2.0.4
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.
12
NeoKey SDK versão 2.0.4
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.
13
NeoKey SDK versão 2.0.4
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.
14
NeoKey SDK versão 2.0.4
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.
15
NeoKey SDK versão 2.0.4
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
16
NeoKey SDK versão 2.0.4
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.
17
NeoKey SDK versão 2.0.4
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).
18
NeoKey SDK versão 2.0.4
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
19
NeoKey SDK versão 2.0.4
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.
20
NeoKey SDK versão 2.0.4
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.
21
NeoKey SDK versão 2.0.4
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.
22
NeoKey SDK versão 2.0.4
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.
23
NeoKey SDK versão 2.0.4
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]
24
NeoKey SDK versão 2.0.4
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.
Nesta versão do nosso SDK disponibilizamos somente a ClientAPI32.dll que pode ser usada
por aplicativos 32 bit, em Windows 32 ou 64 bit.
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
25
NeoKey SDK versão 2.0.4
decifrar os comandos causando estes erros.
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.
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 que 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
Trafego de Debug violado
-303
26
NeoKey SDK versão 2.0.4
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á
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 aceso 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 de entre os computadores, realize
um 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 data configurada está inferior à
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.
27
NeoKey SDK versão 2.0.4
NeoKey indisponível
-2100
Possíveis causas para o erro acima:
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 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).
28
NeoKey SDK versão 2.0.4
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
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
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.
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
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.
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)
int p2, //Tamanho do Parâmetro 2 ou parâmetro auxiliar
29
NeoKey SDK versão 2.0.4
LPSTR param3, //Tamanho do Parâmetro 3 (Ponteiro BYTE)
int p3, //Tamanho do Parâmetro 3 ou parâmetro auxiliar
struct LicenseParameters * Licparam // Estrutura de licenças do NeoKey.);
Parâmetros:
int cmd
(Inteiro) É o comando a ser realizado pelo NeoKey, veja a Tabela 2. (Comandos)
Tabela 2 (Comandos)
Descrição
Login
Gravar na memória (DWORD)
Ler da memória (DWORD)
Criptografar
Descriptografar
Ler a licença
Gravar na memória (WORD)
Ler da memória (WORD)
Ler ID do Hardware
Ler uma página da memória
Gravar uma página da memória
Buscar próximo NeoKey
Reiniciar busca
Logout
Ler o código de atualização (CDC)
Aplicar atualização via código (CPC)
Aplicar atualização via arquivo
Sicronizar OTP (SincOTP)
Login OTP
SetSinc
Comando
1
2
3
4
5
7
8
9
10
11
12
14
15
16
31
32
33
50
51
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
30
NeoKey SDK versão 2.0.4
É 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
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
31
NeoKey SDK versão 2.0.4
Exemplo:
LicenseParameters.ID=0
LicenseParameters.Enable=0
Senha = “1234567890123456”
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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
Int ret =NeoKeyCall (3, Meudado, Endereço, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor lido da memória.
Print (Meudado) >“1234”
32
NeoKey SDK versão 2.0.4
Criptografar - cmd = 4
O comando (4) criptografar 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.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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
importante dimensionar a variável de acordo com essa premissa antes de acessar o comando.
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
33
NeoKey SDK versão 2.0.4
Int ret =NeoKeyCall (5, Meudado, tamanho, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor descriptografado.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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”
34
NeoKey SDK versão 2.0.4
Endereço=0
Int ret =NeoKeyCall (8, Meudado, Endereço, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
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
Int ret =NeoKeyCall (9, Meudado, Endereço, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor lido da memória.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor lido da memória.
Print (HardwareID) > 25700001
35
NeoKey SDK versão 2.0.4
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:
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor lido da memória.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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.
36
NeoKey SDK versão 2.0.4
Exemplo:
Int ret = NeoKeyCall (14, NULL, 0, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
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:
Int ret = NeoKeyCall (15, NULL, 0, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
Logout - cmd = 16
O comando (16) finaliza os acessos a uma licença no NeoKey, impedindo que qualquer
comando possa ser executado.
Exemplo:
Int ret = NeoKeyCall (16, NULL, 0, NULL, 0, NULL, 0, NULL)
If ret = 0 Sucesso ou If ret <> 0 Erro
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)
37
NeoKey SDK versão 2.0.4
If ret = 0 Sucesso ou If ret <> 0 Erro
Print(CDC)
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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
38
NeoKey SDK versão 2.0.4
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.
ArrayRandom = Gerar um array de 8 bytes – randômico
Chamar a função 53 e enviar os dados randômicos ao Hardware
Chamar a função 50 SincOTP
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.
1.
2.
3.
4.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
LoginOTP - cmd = 51
Este dever ser o primeiro comando a ser executado, para que os outros comandos possam
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 (challengeresponse) 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
39
NeoKey SDK versão 2.0.4
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.
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á
necessário gravar novamente o projeto no NeoKey via o DevTool.
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
40
NeoKey SDK versão 2.0.4
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)
OU
int NeoKey_LoginOTP(unsigned char *message, unsigned int size,unsigned int licenseID,
unsigned int Type,unsigned char *HardwareID)
Este dever ser o primeiro comando a ser executado, para que os outros comandos possam
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 tamanho do desafio e da resposta é 16 Bytes, podendo este ser qualquer caractere.
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.
41
NeoKey SDK versão 2.0.4
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 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.
Exemplo:
Senha = “1234567890123456”
HardwareID=”xxxxxxxx”
Int ret = NeoKey_Login(Senha, 16,0, 0, HardwareID)
If ret = 0 Sucesso ou If ret <> 0 Erro
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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 ()
42
NeoKey SDK versão 2.0.4
If ret = 0 Sucesso ou If ret <> 0 Erro
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
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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 é
43
NeoKey SDK versão 2.0.4
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.
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.
Exemplo:
Senha = “1234567890123456”
HardwareID=”xxxxxxxx”
Int ret = NeoKey_Login_Next(Senha, 16,0, 0, HardwareID)
If ret = 0 Sucesso ou If ret <> 0 Erro
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.
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”
44
NeoKey SDK versão 2.0.4
tamanho=16
Int ret = NeoKey_Crypt (Meudado, tamanho)
If ret = 0 Sucesso ou If ret <> 0 Erro
Na variável meudado é retornado o valor criptografado.
Print ( Meudado) > “:/<)*t#Fj!xB{iMn”
NeoKey_Decrypt
int NeoKey_Decrypt(unsigned char *message, unsigned int size)
Permite decifrar/descriptografar uma informação.
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: “:/<)*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)
If ret = 0 Sucesso ou If ret <> 0 Erro
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
)
45
NeoKey SDK versão 2.0.4
Esta função lê informações relativas a uma licença.
Exemplo:
Queremos ler o estado da licença ID = 0.
ID=0
Enable=x
SingleInstance=x
Netusers=x
ExpireDate=”xxxxxxxx” (8 bytes)
Counter=x
Int ret = NeoKey_GetLicense (ID, Enable, SingleInstance, Netusers, ExpireDate, Counter)
If ret = 0 Sucesso ou If ret <> 0 Erro
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]
46
NeoKey SDK versão 2.0.4
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.
[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.
47
NeoKey SDK versão 2.0.4
alarm=1
//Aqui habilitamos se a mensagem de erro será apresentada caso o NeoKey NOW não possa
ser acessado.
counter=100
//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.
48
NeoKey SDK versão 2.0.4
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
49
NeoKey SDK versão 2.0.4
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
50
NeoKey SDK versão 2.0.4
//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.
51