Utilizar o seu OVHcloud Key Management Service (KMS)

Encripte ou assine os seus dados com a API REST regional do Key Management Service (KMS) da OVHcloud

Objetivo

O objetivo deste guia é apresentar as diferentes etapas para interagir com o KMS OVHcloud a fim de encriptar ou assinar os seus dados.

Requisitos

Dispor de uma conta de cliente OVHcloud.
Ter encomendado um KMS OVHcloud.
Ter configurado um método de autenticação para o plano de dados OKMS (token de acesso pessoal, conta de serviço ou certificado de acesso).

Instruções

Comunicar com o KMS

A comunicação com o KMS para as ações de encriptação e de assinatura é feita através das API.

Uma vez que o KMS é regionalizado, o acesso à API é feito diretamente na sua região: https://my-region.okms.ovh.net.

Por exemplo, para um KMS criado na região eu-west-rbx: https://eu-west-rbx.okms.ovh.net

É possível comunicar com o KMS utilizando:

A interface de utilizador Swagger
A CLI OKMS: https://github.com/ovh/okms-cli
O SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Autentique-se através de um token de acesso pessoal, uma conta de serviço ou um certificado de acesso. Para a utilização da API REST, recomenda-se um token de acesso pessoal (PAT) ou uma conta de serviço. Os certificados de acesso são obrigatórios para as integrações KMIP.

Para testar as chamadas à API de forma interativa, utilize a interface Swagger OKMS no endereço https://<region>.okms.ovh.net/swagger/.

Criar uma chave de encriptação através da API

A criação de uma chave pode ser feita através da ou nas API específicas do KMS OVHcloud. Não há diferenças no resultado consoante o método de criação.

Info

As rotas seguintes utilizam o identificador do seu domínio OKMS. É devolvido pela seguinte chamada à API:

GET/okms/resource

Também é apresentado, juntamente com o endpoint regional, no separador Informações gerais do .

No caso das API específicas do KMS OVHcloud, a criação de uma chave é feita através da seguinte API:

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey	Criar ou importar uma CMK

A API espera os seguintes valores:

Campo	Valor	Descrição
name	string	Nome da chave
context	string	Dado de identificação complementar que permite verificar a autenticidade da chave
type	oct, RSA, EC	Tipo da chave: sequência de bytes (oct) para chaves simétricas, RSA (RSA), Elliptic Curve (EC)
size	Integer	Tamanho da chave - ver tabela de correspondência abaixo
operations	Array	Utilização da chave - ver tabela de correspondência abaixo
curve	P-256, P-384, P-521	(opcional) Curva criptográfica para as chaves do tipo EC
extractable	boolean	(opcional) Indica se o material da chave poderá ser exportado - ver a secção Atributos de sensibilidade das chaves de serviço abaixo

Exemplo de criação de uma chave simétrica:

{
  "name": "My first AES key",
  "context": "project A",
  "type": "oct",
  "size": 256,
  "operations": [
    "encrypt",
    "decrypt"
  ]
}

Exemplo de criação de uma chave assimétrica:

{
  "name": "My first RSA key",
  "context": "project A",
  "type": "RSA",
  "size": 4096,
  "operations": [
    "sign",
    "verify"
  ]
}

Exemplo de criação de uma chave EC:

{
  "name": "My first EC key",
  "context": "project A",
  "type": "EC",
  "operations": [
    "sign",
    "verify"
  ],
  "curve": "P-256"
}

Os tamanhos e as operações possíveis em função do tipo de chave são os seguintes:

oct:
- tamanho: 128, 192, 256
- operações:
  - encrypt, decrypt
  - wrapKey, unwrapKey
RSA:
- tamanho: 2048, 3072, 4096
- operações:
  - sign, verify
  - wrapKey, unwrapKey
EC:
- tamanho: não especificar
- curve: P-256, P-384, P-521
- operações: sign, verify

Info

Nas chaves RSA, wrapKey / unwrapKey são mutuamente exclusivas com sign / verify.

Importar uma chave de encriptação

Ao criar uma chave, é possível importar uma chave existente em texto claro no formato JWK.

Warning

A importação de material de chave em texto claro não é recomendada para as chaves que devem permanecer de confiança. Prefira o BYOK seguro com encapsulamento RSA assimétrico.

Para isso, pode adicionar um campo complementar keys no corpo do pedido:

{
  "name": "My imported key",
  "keys": [
    {
      "kid": "string",
      "use": "string",
      "key_ops": [
        "string"
      ],
      "alg": "string",
      "kty": "oct",
      "n": "string",
      "e": "string",
      "k": "string",
      "crv": "string",
      "x": "string",
      "y": "string",
      "d": "string",
      "dp": "string",
      "dq": "string",
      "p": "string",
      "q": "string",
      "qi": "string"
    }
  ]
}

A chave deve estar no formato JSON Web Key (JWK). O valor dos campos contidos na tabela segue a documentação da RFC 7518.

Gerir as chaves de encriptação

Para gerir as chaves de encriptação, estão disponíveis várias API:

Método	Caminho	Descrição
GET	/api/{okmsId}/v1/servicekey	Lista as chaves de encriptação disponíveis
DELETE	/api/{okmsId}/v1/servicekey/{keyId}	Elimina uma chave de encriptação
POST	/api/{okmsId}/v1/servicekey/{keyId}/activate	Ativa uma chave de encriptação
POST	/api/{okmsId}/v1/servicekey/{keyId}/deactivate	Desativa uma chave de encriptação

A desativação de uma chave de encriptação implica que esta deixará de poder ser utilizada, embora a chave permaneça presente no KMS.

A eliminação de uma chave de encriptação só é possível numa chave previamente desativada.

Warning

A eliminação de uma chave de encriptação é definitiva. Todos os dados encriptados com ela ficarão definitivamente inacessíveis.

Atributos de sensibilidade das chaves de serviço

Quando cria ou obtém uma chave de serviço, os indicadores de sensibilidade e extraibilidade são devolvidos no objeto attributes da resposta GET (a par de outros metadados como state). Apenas extractable é definível pelo utilizador (na criação ou via PATCH). Os outros indicadores são definidos pelo KMS. Definir extractable como true fixa definitivamente never_extractable como false.

Atributo	Definível pelo utilizador?	Descrição
`extractable`	Sim (criação / PATCH)	Se `true`, o material da chave pode ser exportado (em texto claro ou encapsulado, consoante a classe da chave). Por defeito: `false` — exceto as chaves apenas públicas, cujo valor por defeito é `true`.
`never_extractable`	Não	`true` se a chave nunca foi extraível desde a criação no KMS. As chaves importadas com BYOK ou por importação em texto claro têm `never_extractable` definido como `false`, porque o material existia fora do KMS antes da importação. Ativar a extração também limpa este indicador de forma permanente.
`sensitive`	Não	`true` quando a chave só pode ser extraída após ser encapsulada (o que também exige que `extractable` seja `true`). As chaves secretas e privadas (material AES/`oct` e RSA/EC privado) são sempre consideradas sensíveis.
`always_sensitive`	Não	`true` se a chave foi sempre sensível desde a criação.

Exemplo de resposta GET (campos abreviados):

{
  "id": "<key-id>",
  "name": "aes-to-export",
  "type": "oct",
  "attributes": {
    "state": "active",
    "extractable": true,
    "never_extractable": false,
    "sensitive": true,
    "always_sensitive": true
  }
}

Para extrair uma chave em segurança, defina extractable como true apenas para a operação de exportação, exporte-a com encapsulamento RSA e volte a defini-lo como false. Consulte Exportar uma chave encapsulada.

Encriptar dados com o KMS

Encriptação no KMS

O KMS OVHcloud dispõe de uma API de encriptação dedicada para a encriptação de pequenos volumes de dados (menos de 4 kB).

Trata-se do método mais simples, mas que não apresenta o melhor desempenho.

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/encrypt	Encriptação de dados com uma CMK

A API espera os seguintes valores:

Campo	Valor	Descrição
plaintext	string	Dado a encriptar
context	string	Dado de identificação complementar que permite verificar a autenticidade do dado

Exemplo de encriptação

{
  "plaintext": "My secret data",
  "context": "Project A"
}

A API devolve em seguida o dado encriptado num campo ciphertext:

{
  "ciphertext": "Encrypted data",
}

A desencriptação do dado é feita de forma inversa através da API:

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/decrypt	Desencriptação de dados com uma CMK

A API espera os seguintes valores:

Campo	Valor	Descrição
ciphertext	string	Dado a desencriptar
context	string	Dado de identificação complementar que permite verificar a autenticidade do dado

O campo context deve ter o mesmo valor que o indicado durante a encriptação.

Encriptação com uma Data Key (DK)

Para obter mais desempenho, é possível gerar uma Data Key (DK) a partir de uma chave simétrica (AES) para a utilizar a partir da sua aplicação. A chave AES utilizada deve ter sido gerada com as operações wrapKey e unwrapKey.

A geração de uma DK é feita através da seguinte API:

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey	Gerar uma DK derivada de uma CMK

A API espera os seguintes valores:

Campo	Valor	Descrição
name	string	Nome da chave
size	Integer	Tamanho da chave (64-4096)

Exemplo de geração de uma Data Key:

{
  "name": "My Data Key",
  "size": 4096
}

A API devolverá em seguida a Data Key:

{
  "key": "string",
  "plaintext": "string"
}

key: chave encriptada codificada em base64. Esta informação deve ser armazenada com o dado encriptado e será utilizada para a desencriptação pelo KMS.
plaintext: chave em texto simples codificada em base64. Esta informação deve ser eliminada assim que a encriptação estiver concluída e não deve ser guardada numa cópia de segurança.

A utilização da Data Key é feita em seguida através de algoritmos de encriptação como o AES-GCM, que não é abordado nesta documentação.

Inversamente, é possível recuperar a versão desencriptada de uma Data Key através da seguinte API:

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey/decrypt	Desencriptação de uma DK

A API espera os seguintes valores:

Campo	Valor	Descrição
key	string	Data Key encriptada

E devolve a Data Key desencriptada num campo plaintext.

Assinar com o KMS

A assinatura de um ficheiro é feita através da chave privada de um par de chaves assimétricas.

Algoritmos suportados

O KMS OVHcloud suporta a seguinte lista de algoritmos de assinatura:

RSASSA-PKCS1 v1.5

Nome	Digital Signature Algorithm
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS384	RSASSA-PKCS1-v1_5 using SHA-384
RS512	RSASSA-PKCS1-v1_5 using SHA-512

Segundo a documentação da RFC 7518.

ECDSA

Nome	Digital Signature Algorithm
ES256	ECDSA using P-256 and SHA-256
ES384	ECDSA using P-384 and SHA-384
ES512	ECDSA using P-521 and SHA-512

Segundo a documentação da RFC 7518.

RSASSA-PSS

Nome	Digital Signature Algorithm
PS256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512	RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Segundo a documentação da RFC 7518.

Assinatura de uma mensagem

Dado que a chave privada não pode ser extraída em texto claro do KMS, a assinatura só pode ser feita diretamente no KMS.

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/sign	Assinatura de um ficheiro

A API espera os seguintes valores:

Campo	Valor	Descrição
message	string	Mensagem a assinar em formato base64
alg	string	Algoritmo de assinatura
isdigest	boolean	Indica se a mensagem já foi sujeita a hash

Exemplo de assinatura:

{
  "message": "SGVsbG8gV29ybGQ=",
  "alg": "RS256",
  "isdigest": false
}

A API devolverá em seguida a assinatura do ficheiro:

{
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw=="
}

Verificação de um ficheiro

A verificação de um ficheiro pode ser feita diretamente no KMS ou utilizando a chave pública.

No KMS, é possível utilizar a seguinte API:

Método	Caminho	Descrição
POST	/api/{okmsId}/v1/servicekey/{keyId}/verify	Verificação de uma assinatura

A API espera os seguintes valores:

Campo	Valor	Descrição
message	string	Mensagem a assinar
signature	string	Assinatura associada à mensagem
alg	string	Algoritmo de assinatura
isdigest	boolean	Indica se a mensagem já foi sujeita a hash

Exemplo de verificação

{
  "message": "SGVsbG8gV29ybGQ=",
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw==",
  "alg": "RS256",
  "isdigest": false
}

A API devolverá em seguida o resultado da verificação:

{
  "result": true
}

Quer saber mais?

Importar e exportar chaves no OVHcloud KMS com BYOK

Métodos de autenticação OKMS

Como ligar um produto compatível utilizando o protocolo KMIP

Fale com a nossa comunidade de utilizadores.

Esta página foi útil?