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.



Argumentos:

first: Int

after: String

last: Int

before: String






Argumentos:

input: EncryptInput obrigatório



Argumentos:

input: DecryptInput obrigatório



Argumentos:

input: CreateHashInput obrigatório






Campos:

keyLabel

:

String

idKeyLabel

:

Int


Campos:

clientMutationId

:

String

keyLabel

:

String obrigatório

inputFormatFlag

:

String obrigatório

outputFormatFlag

:

String obrigatório

iv

:

String

message

:

String obrigatório

padding

:

PaddingType


Campos:

clientMutationId

:

String

keyLabel

:

String obrigatório

inputFormatFlag

:

String obrigatório

outputFormatFlag

:

String obrigatório

iv

:

String obrigatório

message

:

String obrigatório


Campos:

clientMutationId

:

String

hashIdentifier

:

HashIdentifierType obrigatório

inputFormatType

:

FormatType obrigatório

message

:

String obrigatório





Campos:

hasPreviousPage

:

Boolean obrigatório

hasNextPage

:

Boolean obrigatório

startCursor

:

String

endCursor

:

String


Campos:

mode

:

String obrigatório

keyType

:

String obrigatório

key

:

String obrigatório

ksnDescriptor

:

String

keySerialNumber

:

String

lmkIdentifier

:

String obrigatório

padding

:

PaddingType

delimiter

:

String


Campos:

clientMutationId

:

String

id

:

ID obrigatório

keyLabel

:

String obrigatório

properties

:

HsmProperties obrigatório


Campos:

cursor

:

String obrigatório

node

:

KeyLabel


Campos:

pageInfo

:

PageInfo obrigatório

edges

:

lista de KeyLabelEdge

totalCount

:

Int


Campos:

clientMutationId

:

String

iv

:

String

message

:

String obrigatório


Campos:

clientMutationId

:

String

iv

:

String

message

:

String obrigatório


Campos:

clientMutationId

:

String

message

:

String obrigatório





Valores possíveis:


ZERO


ANSI_X_923


ISO_7816_4


PKCS7





Valores possíveis:


MD5


SHA_1


SHA_224


SHA_256


SHA_384


SHA_512


ISO_10118_2





Valores possíveis:


TEXT


HEX_ENCODED