Hardware Security Module (HSM)

Esta interface de programação permite a manipulação de chaves e algoritmos de criptografia em alto nível e agnóstico ao hardware.

Como funciona

Primeiros passos

  1. Leia Introdução ao GraphQL, com exemplos reais da nossa API.
  2. Crie um usuário no portal do desenvolvedor.
  3. Cadastre sua primeira aplicação.
  4. Utilize o dashboard para acessar suas configurações de acesso.
  5. Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

O HSM é um hardware dedicado a uma variedade operações criptográficas como encriptação, gestão de chaves, troca de chaves e decriptação. Esse tipo de hardware possui características específicas que garantem a segurança da informação de diversas maneiras dentro de um ambiente totalmente confiável. Esta api permite a utilização de alguns dos serviços fornecidos pelo HSM de forma agnóstica a plataforma e tecnologia.

Labels são chaves de criptografia fornecidas pelo usuário da API que poderão ser utilizadas na criptografia e descriptografia dos dados que o usuário deseja proteger.

O usuário da plataforma ELO poderá gerenciar suas labels cadastrando, listando, editando e removendo labels. Nota: Para se utilizar o recurso de criptografia e descriptografia desta API é obrigatório possuir pelo menos uma label cadastrada.

Para cadastrar uma label, utilize a seguinte mutation, passando no header da requisição seu access_token obtido no login:

mutation{
    createKeyLabel(
        input:{
            clientMutationId: "123456"
            keyLabel: "String"
            properties: {
                mode: "00"
                keyType: "FFF"
                key: "S10128D0AN00E000095F85A5E61E91C7AC821B3000033844F7E23922D6D1E15411BB278ABFEFE8B6FA7FEBA536ED983314F37468C0E3118F7FA71E14C39B51786"
                ksnDescriptor: "00"
                keySerialNumber: "00"
                lmkIdentifier: "00"
                padding: ISO_7816_4
                delimiter: "%"
            }            
        }
    )
    {
        clientMutationId
        id
        keyLabel
        properties{
            mode
            keyType
            key
            ksnDescriptor
            keySerialNumber
            lmkIdentifier
            padding
        }
    }
}

Para listar as labels cadastradas utilize a seguinte query:

query{
    keyLabels(
        first: 3, after: "10",
        filter: {keyLabel: "TESTE"}
    )
    {
        edges{
            node{
                clientMutationId
                id
                keyLabel
                properties{
                    mode
                    keyType
                    key
                    ksnDescriptor
                    keySerialNumber
                    lmkIdentifier
                    padding
                }
            }
        }
    }
}

Tendo uma label cadastrada é possível editar suas propriedades através da mutation a seguir informando o id (retornado na query keyLabels) da label que você deseja alterar:

mutation{
    updateKeyLabel(
        input:{
            clientMutationId: "123456"
            id: "54321"
            keyLabel: "String"
            properties: {
                mode: "String"
                keyType: "FFF"
                key: "String"
                ksnDescriptor: "String"
                keySerialNumber: "String"
                lmkIdentifier: "String"
                padding: PKCS7
                delimiter: "%"
            }
        }
    )
    {
        clientMutationId
        id
        keyLabel
        properties{
            mode
            keyType
            key
            ksnDescriptor
            keySerialNumber
            lmkIdentifier
            padding
        }
    }
}

Para excluir uma label utilize a mutation a seguir fornecendo o id da label que você deseja excluir:

NOTA: Ao excluir uma label, as criptografias efetuadas por ela não poderam mais ser abertas.

mutation{
    deleteKeyLabel(
        input:{
            clientMutationId: "123456"
            id: 11111
        }
    )
    {
        clientMutationId
        id
        keyLabel
        properties{
            mode
            keyType
            key
            ksnDescriptor
            keySerialNumber
            lmkIdentifier
            padding
        }
    }
}

Tendo sua label cadastrada agora é possível utilizar a criptografia fornecida pelo HSM. Utilize a mutation abaixo e o resultado da criptografia poderá ser obtido pelo campo de retorno message.

mutation {
    encrypt(input:{
            clientMutationId: "123456"
            keyLabel: "String"
            inputFormatFlag: "String"
            outputFormatFlag: "String"
            iv: "String"
            message: "String"
            padding: ZERO
    })
    {
        clientMutationId
        iv
        message
    }
}

Detalhes dos atributos:

  • keyLabel: Nome da label cadastrada no ambiente da API de HSM.
  • inputFormatFlag: Formato que está sendo passado no campo message.
    • Valor 0 (Zero): indica que o campo message está no formato binário, este formato indica que os dados estão no formato de Hexadecimal. Como exemplo a palavra “teste” no formato 0 seria “7465737465”.
    • Valor 1 (Um): indica que o campo message está no formato Hexadecimal, este formato indica que os dados estão no formato hexadecimal do hexadecimal. Como exemplo a palavra “teste” no formato 1 seria “37343635373337343635”.
    • Valor 2 (Dois): indica que o campo message está no formato texto, este formato indica que os dados estão em Texto. Como exemplo a palavra “teste” no formato 2 seria “teste”.
  • outputFormatFlag: Formato que está sendo retornado no campo message do Json de resposta. São os mesmo valores e descrições do inputFormatFlag. Nem todas as conversões serão possíveis, dependendo assim dos dados informados na mensagem.
  • iv: campo utilizado junto com a chave de criptografia. Campo informado pelo usuário da API e retornado ao mesmo para casos de chamadas em bloco. Normalmente com tamanho de 16 H.
  • message: campo que contém a informação a ser criptografada no formato definido pelo campo inputFormatFlag.
  • padding: tipo de padding a ser utilizado na mensagem. Hoje na API temos 4 tipos de padding, sendo eles ZERO, ANSI_X_923, ISO_7816_4 e PKCS7. Para mais detalhes sobre como funciona cada tipo olhar documentação do padding na internet.

Para descriptografar mensagens previamente criptografadas pela API HSM utilize a seguinte mutation:

mutation{
    decrypt(input:{
            clientMutationId: "123456"
            keyLabel: "String"
            inputFormatFlag: "String"
            outputFormatFlag: "String"
            iv: "String"
            message: "String"
    })
    {
        clientMutationId
        iv
        message
    }
}

Os atributos seguem os mesmos conceitos e descrições comentados no recurso de criptografia. Um ponto de observação está no atributo message, na entrada este campo deve ser preenchido com a mensagem criptografada e no retorno da mutation irá retornar a mensagem descriptografada junto com informações do padding fornecido na criptografia efetuada anteriormente. Nesta chamada não existe o atributo padding.

Também é possível utilizar a API para criar hashs das informações, utilizando a mutation a seguir:

mutation{
    createHash(input:{
            clientMutationId: "123456"
            hashIdentifier: SHA_256
            inputFormatType: TEXT
            message: "String"
    })
    {
        clientMutationId
        message
    }
}

Detalhes dos atributos:

  • hashIdentifier: identifica qual método será gerado o hash. Hoje a API possuí 7 formas de gerar o hash, sendo elas SHA_1, MD5, ISO_10118_2, SHA_224, SHA_256, SHA_384 e SHA_512.
  • inputFormatType: identifica o formato que está o campo message. Hoje a API possuí 2 formas sendo elas TEXT e HEX_ENCODED.
  • message: mensagem a partir da qual será gerada o hash.

Critério de filtro para keyLabel

Parâmetros de entrada

keyLabel (String) Se null ou vazio, não realiza filtragem. Label de atalho para realizar a requisição.

idKeyLabel (Int) Se null ou vazio, não realiza filtragem. ID do Label de atalho para realizar a requisição.

Entrada para a mutação createKeyLabel()

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!)

properties (HsmPropertiesInput!)

Entrada para a mutação updateKeyLabel()

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

id (ID!)

keyLabel (String!)

properties (HsmPropertiesInput!)

Entrada para a mutação deleteKeyLabel()

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

id (ID!)

Entrada responsavel por criptografia de uma mensagem de acordo com os dados informados.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!) Label de atalho para realizar a requisição.

inputFormatFlag (String!) Formato da mensagem de entrada que será encryptada. 0 - BINARY || 1 - HEX_ENCODED || 2 - TEXT

outputFormatFlag (String!) Formato da mensagem de saída encryptada. 0 - BINARY || 1 - HEX_ENCODED

iv (String) Valor usado em conjunto com a chave de criptografia. Caso seja NULL será gerado uma chave para complementar a criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada. Tamanho maximo aceitado é de 32000 caracteres.

padding (PaddingType) Caso seja NULL, será utilizado o valor da KeyLabel.

Entrada responsavel por de-criptografia de uma mensagem de acordo com os dados informados.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!) Label de atalho para realizar a requisição.

inputFormatFlag (String!) Formato da mensagem de entrada que será decryptada. 0 - BINARY || 1 - HEX_ENCODED

outputFormatFlag (String!) Formato da mensagem de saída decryptada. 0 - BINARY || 1 - HEX_ENCODED || 2 - TEXT

iv (String!) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Entrada para a mutação createHash()

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

hashIdentifier (HashIdentifierType!)

inputFormatType (FormatType!)

message (String!) Mensagem que será utilizada para gerar o hash.

Conexão de keyLabel em conformidade com o Relay.

Parâmetros de entrada

pageInfo (PageInfo!) Cursor opaco para ser usado com queries (consultas) after ou before.

edges ([KeyLabelEdge]) Lista de arestas que compõem esta conexão.

totalCount (Int) Contagem total de objetos nesta conexão.

Arestas são limitadas a cursores before e after, assim como primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente menor que a conexão como um todo.

totalCount, se não for null, indica o número total de itens na conexão considerando-se o filtro.

PageInfo compatível com Relay.

Parâmetros de entrada

hasPreviousPage (Boolean!)

hasNextPage (Boolean!)

startCursor (String)

endCursor (String)

Aresta de conexão contendo KeyLabel em conformidade com o Relay.

Parâmetros de entrada

cursor (String!) Cursor opaco para ser usado com queries (consultas) after ou before.

node (KeyLabel) O objeto KeyLabel que compõe essa aresta de conexão.

Descrição que identifica a chave.

Parâmetros de entrada

clientMutationId (String)

id (ID!) Identificador Global Único para este objeto

keyLabel (String!)

properties (HsmProperties!)

Parâmetros utilizadados para a criptografia.

Parâmetros de entrada

mode (String!) Modo da criptografia.

keyType (String!) Indica o tipo da chave para ser usado. Valores possíveis: FFF, 009, 609, 809, 00A, 00B, 30B

key (String!) A chave de criptografia.

ksnDescriptor (String) O descritor do número serial da chave (key serial number).

keySerialNumber (String) O número serial da chave provido pela PIN pad.

lmkIdentifier (String!) Identifiacor do LMK.

padding (PaddingType) Padding será utilizado para completar a mensagem que será enviada ao HSM.

Retorno da a mutação createKeyLabel()

Parâmetros de entrada

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Retorno da mutação updateKeyLabel()

Parâmetros de entrada

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Retorno da mutação deleteKeyLabel()

Parâmetros de entrada

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Retorno da mutação Encrypt().

Compatível com Relay.

Parâmetros de entrada

clientMutationId (String)

iv (String) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Retorno da mutação Decrypt().

Compatível com Relay.

Parâmetros de entrada

clientMutationId (String)

iv (String) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Retorno da mutação createHash()

Parâmetros de entrada

clientMutationId (String)

message (String!) Hash, conforme o tipo selecionado.

Tipo que Indica qual padding será utilizado para completar a mensagem que será enviada ao HSM.

Parâmetros de entrada

ZERO Se utilizar esse valor todos os bytes que precisam ser preenchidos são preenchidos com zero. ISO/IEC 9797-1.[7].

ANSI_X_923 Em ANSI X.923 bytes preenchidos com zeros são preenchidos e o último byte define os limites de preenchimento ou o número de bytes preenchidos.

ISO_7816_4 ISO/IEC 7816-4:2005[5] is identical to the bit padding scheme, applied to a plain text of N bytes. This means in practice that the first byte is a mandatory byte valued '80' (Hexadecimal) followed, if needed, by 0 to N-1 bytes set to '00', until the end of the block is reached. ISO/IEC 7816-4 itself is a communication standard for smart cards containing a file system, and in itself does not contain any cryptographic specifications.

PKCS7 PKCS#7 é descrito no RFC 5652.

O preenchimento é em bytes inteiros. O valor de cada byte adicionado é o número de bytes que são adicionados, ou seja, N bytes, cada um dos valores N são adicionados. O número de bytes adicionados dependerá do limite do bloco ao qual a mensagem precisa ser estendida. Esse método de preenchimento (bem como os dois anteriores) é bem definido se e somente se N for menor que 256.

Query (consulta) de labels cadastradas

Parâmetros de entrada

first (Int) Limita a lista às primeiras entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para frente.

after (String) Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.

last (Int) Limita a lista às últimas entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para trás.

before (String) Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.

filter (KeyLabelFilterInput) Aplica filtro, se provido.

Parâmetros de saída

pageInfo (PageInfo!) Cursor opaco para ser usado com queries (consultas) after ou before.

edges ([KeyLabelEdge]) Lista de arestas que compõem esta conexão.

totalCount (Int) Contagem total de objetos nesta conexão.

Arestas são limitadas a cursores before e after, assim como primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente menor que a conexão como um todo.

totalCount, se não for null, indica o número total de itens na conexão considerando-se o filtro.

Mutation que cadastra um novo label.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!)

properties (HsmPropertiesInput!)

Parâmetros de saída

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Mutation que atualiza uma label.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

id (ID!)

keyLabel (String!)

properties (HsmPropertiesInput!)

Parâmetros de saída

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Mutation que exclui um label.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

id (ID!)

Parâmetros de saída

clientMutationId (String)

id (ID!)

keyLabel (String!)

properties (HsmProperties!)

Mutation responsável para criptografia de uma mensagem de acordo com os dados informados.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!) Label de atalho para realizar a requisição.

inputFormatFlag (String!) Formato da mensagem de entrada que será encryptada. 0 - BINARY || 1 - HEX_ENCODED || 2 - TEXT

outputFormatFlag (String!) Formato da mensagem de saída encryptada. 0 - BINARY || 1 - HEX_ENCODED

iv (String) Valor usado em conjunto com a chave de criptografia. Caso seja NULL será gerado uma chave para complementar a criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada. Tamanho maximo aceitado é de 32000 caracteres.

padding (PaddingType) Caso seja NULL, será utilizado o valor da KeyLabel.

Parâmetros de saída

clientMutationId (String)

iv (String) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Mutation responsável para de-criptografia de uma mensagem de acordo com os dados informados.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

keyLabel (String!) Label de atalho para realizar a requisição.

inputFormatFlag (String!) Formato da mensagem de entrada que será decryptada. 0 - BINARY || 1 - HEX_ENCODED

outputFormatFlag (String!) Formato da mensagem de saída decryptada. 0 - BINARY || 1 - HEX_ENCODED || 2 - TEXT

iv (String!) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Parâmetros de saída

clientMutationId (String)

iv (String) Valor usado em conjunto com a chave de criptografia.

message (String!) A mensagem a ser criptografada ou decriptografada.

Mutation que transforma a mensagem informada em um hash especifico.

Parâmetros de entrada

clientMutationId (String) Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.

hashIdentifier (HashIdentifierType!)

inputFormatType (FormatType!)

message (String!) Mensagem que será utilizada para gerar o hash.

Parâmetros de saída

clientMutationId (String)

message (String!) Hash, conforme o tipo selecionado.