Cenário: Criar uma Instância Digital Twin que use um Certificado mTLS

Se você receber dados de um dispositivo, deverá usar a autenticação com sua instância de gêmeo digital. Este cenário explica como usar um certificado para autenticar uma instância de gêmeo digital para um dispositivo.

O mTLS (TLS mútuo) é um protocolo de segurança que garante que o cliente e o servidor autenticem a identidade um do outro durante a comunicação. Ao contrário do TLS padrão, que autentica apenas o servidor, o mTLS adiciona uma camada de confiança ao exigir que o cliente e o servidor apresentem certificados válidos. Como alternativa, se você estiver configurando um ambiente de teste, poderá usar um segredo para autenticar a instância de gêmeo digital.
  1. Criar uma Chave
  2. Criar uma Autoridade de Certificação
  3. Gerar uma nova chave privada
  4. Criar um certificado gerenciado externamente
  5. Criar uma instância de gêmeo digital que use um certificado
  6. Obter detalhes da instância de um gêmeo digital
  7. Assinar um tópico usando MQTTx
  8. Exibir dados do dispositivo no APEX

Melhores práticas
  • Rotacionar certificados com frequência.
  • Limitar períodos de validade do certificado.
  • Armazene chaves privadas usando o serviço Vaults.
  • Monitorar e auditar tentativas de conexão.

Antes de Começar

Certifique-se de ter as permissões necessárias. Um administrador concede acesso criando as políticas necessárias. Para obter mais informações, consulte Pré-requisitos para obter as políticas necessárias para certificados e Detalhes da Política da Plataforma Internet of Things (IoT) para obter as políticas necessárias para recursos do IoT.

Políticas de certificado

Ao criar uma instância de gêmeo digital se você usar um certificado para autenticação, precisará da política a seguir para que o domínio IoT possa ler o certificado.

Deixe que qualquer IoT usuário leia certificados em um compartimento específico para um domínio IoT:
Allow any-user to {CERTIFICATE_BUNDLE_READ, CERTIFICATE_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'
Allow any-user to {CERTIFICATE_AUTHORITY_BUNDLE_READ, CERTIFICATE_AUTHORITY_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'
Allow any-user to {CABUNDLE_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'

Etapa 1: Criar uma Chave

Você deve ter uma chave de criptografia simétrica protegida por hardware existente no OCI (Oracle Cloud Infrastructure). Para verificar se você tem uma Chave de criptografia principal ou para criar uma nova:

  1. Vá para Identidade e Segurança e selecione Vault.
  2. Selecione o Compartimento que deseja usar para seus recursos IoT.
  3. Para criar uma chave, selecione Criar Chave e siga as instruções em Criando uma Chave de Criptografia Principal.
  4. Ou na lista de Vaults, selecione o menu Ações ao lado do Vault que você deseja usar e, em seguida, selecione Exibir Detalhes do Vault.
  5. Selecione Chaves de criptografia mestras para exibir Chaves. Selecione Exibir Detalhes da Chave para localizar o Modo de Proteção e confirmar se ele é HSM (Módulo de Segurança de Hardware).

Etapa 2: Criar uma Autoridade de Certificação

Use o serviço Certificates para criar uma autoridade de certificação raiz (CA) ou uma CA subordinada. Para obter mais informações, consulte Criando uma Autoridade de Certificação.

Este exemplo de tarefa explica como emitir um certificado com uma chave privada que você gerencia externamente usando uma CA subordinada.

Você já deve ter uma CA raiz para criar uma CA subordinada.

  1. Faça log-in como Administrador, com as políticas corretas para executar essas ações. Você deve ter o nível apropriado de acesso de segurança para criar uma CA.
  2. Na página da lista Autoridades de Certificação, selecione Criar Autoridade de Certificação. Se precisar de ajuda para localizar a página da lista, consulte Listando Autoridades de Certificação.
  3. Selecione Compartimento e, em seguida, selecione o compartimento no qual deseja criar a CA.
  4. Em Tipo de Autoridade de Certificação, selecione o tipo Subordinar Autoridade de Certificação: qualquer CA que não seja a CA raiz em uma hierarquia que contenha outras CAs.
  5. (Opcional) Informe um nome de exibição exclusivo para o CA. Esse nome ajuda a identificar a CA para fins administrativos, mas ele não aparece como parte do certificado de CA. Evite digitar informações confidenciais.
    Observação

    Duas CAs em uma tenancy não podem compartilhar o mesmo nome, incluindo CAs com exclusão pendente.
  6. (Opcional) Para aplicar tags, selecione Mostrar Opções de Tag. Para obter mais informações sobre tags, consulte Tags de Recurso.
  7. Selecione Próximo.
  8. Especifique informações sobre o assunto. As informações do assunto incluem pelo menos um nome comum (CN) para identificar o proprietário do certificado de CA. Dependendo do uso pretendido do certificado, o assunto poderá identificar uma pessoa, organização, terminal do computador ou um dispositivo. O formato das informações do titular deve estar em conformidade com os padrões do RFC 5280. Caracteres curinga podem ser usados para emitir um certificado de vários nomes de domínio ou subdomínio.
  9. Selecione Próximo.
  10. Em Configuração de Autoridade, confirme ou selecione o vault que contém a chave de criptografia que você deseja usar para o certificado da CA. Opcionalmente, selecione Alterar Compartimento para especificar outro compartimento. Para obter informações sobre como criar e gerenciar vaults, consulte Gerenciando Vaults.
  11. Em Chave, selecione a chave no vault que você deseja usar. A lista inclui apenas as chaves assimétricas no vault porque o serviço Certificates suporta apenas chaves assimétricas. Você pode selecionar entre as chaves Rivest-Shamir-Adleman (RSA) de 2.048 bits ou 4.096 bits. Também é possível selecionar chaves de algoritmo de assinatura digital de criptografia de curva elíptica (ECDSA) que tenham um ID de curva elíptica NIST_P384. Especificamente, a lista inclui apenas esses tipos de chaves assimétricas que são protegidas por um módulo de segurança de hardware (HSM). Os certificados não suportam o uso de chaves protegidas por software. Para obter mais informações sobre como criar e gerenciar chaves, consulte Gerenciando Chaves.
  12. Em Algoritmo de Assinatura, dependendo da família de algoritmos-chave, selecione uma das seguintes opções:
    • SHA256_WITH_RSA: Chave RSA com uma função de hash SHA-256
    • SHA384_WITH_RSA: Chave RSA com uma função de hash SHA-384
    • SHA512_WITH_RSA: Chave RSA com uma função de hash SHA-512
    • SHA256_WITH_ECDSA: Chave ECDSA com uma função de hash SHA-256
    • SHA384_WITH_ECDSA: Chave ECDSA com uma função de hash SHA-384
    • SHA512_WITH_ECDSA: Chave ECDSA com uma função de hash SHA-512
  13. Selecione Próximo.
  14. Configure a regra de expiração. Em Duração Máxima de Validade para Certificados (Dias), especifique o número máximo de dias que um certificado emitido por esta CA pode ser válido. Recomenda-se usar um período de validade de no máximo 90 dias.
  15. Na página Configuração de Revogação, se você não quiser configurar uma lista de revogação do certificado (CRL), marque a caixa de seleçãoIgnorar Revogação.
  16. Selecione Próximo.
  17. Confirme se as informações estão corretas e selecione Criar Autoridade de Certificação. Pode levar alguns minutos para criar recursos relacionados a certificados.
  18. Se a Autoridade de Certificação tiver sido criada com sucesso, os detalhes do resumo serão exibidos.

Etapa 3: Gerar uma Nova Chave Privada

Crie uma chave privada e uma CSR (certificate ssigning request, solicitação de assinatura de certificado) usando OpenSSL.

Observação

Para fins de segurança, considere executar esta etapa no dispositivo para manter a chave privada e nunca compartilhar a chave externamente.
  1. Use esse comando para gerar uma nova chave privada private.pem e uma solicitação de assinatura de certificado csr.pem com criptografia RSA de 2048 bits. Este exemplo mostra o uso do parâmetro -nodes que especifica sem proteção por senha e usa as extensões v3_req.
    openssl req -nodes -newkey rsa:2048 -keyout private.pem -out csr.pem -extensions v3_req
    Observação

    Se você estiver usando o Linux, por padrão, o arquivo OpenSSL.cnf comentará a extensão, por exemplo, se você vir algo assim no arquivo de configuração OpenSSL: /etc/pki/tls/openssl.cnf
     # req_extensions = v3_req # The extensions to add to a certificate request
    Em seguida, remova o # para cancelar o comentário das extensões, de modo que o arquivo seja semelhante a este:
    req_extensions = v3_req  # The extensions to add to a certificate request
    Para verificar se OpenSSL está usando extensions v3_req, você pode verificar se a saída contém:
    X509v3 extensions:
        X509v3 Basic Constraints: critical
            CA:FALSE
  2. Este exemplo mostra os campos de entrada de solicitação de certificado e os valores de exemplo. Insira as informações que serão incorporadas ao seu relatório de certificado, como um DN (Distinguished Name - Nome Distinto).

    Informe o nome comum. Você pode encontrar o nome comum na guia Informações do Assunto da página de detalhes Certificado. Consulte a etapa 8 Criar uma Autoridade de Certificação ou para obter ajuda para encontrar a página de detalhes do certificado. Consulte Listando Certificados:
    Country Name (2 letter code) []: US
    State or Province Name (full name) [Some-State]:
    Locality Name (eg, city) []:
    Organization Name (eg, company) []:
    Organizational Unit Name (eg, section) []:
    Common Name (Enter common name from the certificate details.) []:common-name
    Email Address [your@email.com]:
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:
    An optional company name []:

Etapa 4: Criar um Certificado Gerenciado Externamente

Você pode gerar uma Solicitação de Assinatura de Certificado (CSR) e chave privada no servidor em que planeja instalar o certificado e, em seguida, submeter essa CSR a uma CA para emitir um certificado, enquanto gerencia a chave privada externamente.

Esta tarefa descreve como emitir um certificado com uma chave privada que você gerencia externamente. Para obter mais informações sobre outras maneiras de usar um certificado, consulte Criando um Certificado para Gerenciar Externamente e Gerenciando Certificados.
  1. Na Console, abra o menu de navegação e selecione Identidade e Segurança.
  2. Na página de lista Certificados, a lista de Autoridade de Certificação de um compartimento específico é exibida.
  3. Localize o Certificado com o qual deseja trabalhar e selecione o menu Ações no final da linha.
  4. Selecione Certificado de Emissão.
  5. Em Tipo de Certificado, para emitir um certificado de uma CA do serviço Certificates gerenciada por uma CA externa de terceiros, selecione Emitido por CA interna e gerenciado externamente.
  6. Informe um nome de exibição exclusivo para o certificado. Evite digitar informações confidenciais.
    Observação

    Dois certificados na tenancy não podem compartilhar o mesmo nome, incluindo certificados com exclusão pendente.
  7. (Opcional) Informe uma descrição para ajudar a identificar o certificado. Evite digitar informações confidenciais.
  8. Para certificados gerenciados por uma CA de terceiros, não é necessário fornecer informações de assunto. Em vez disso, selecione Próximo.
  9. Em Solicitação de Assinatura de Certificado, forneça o conteúdo do certificado selecionando Fazer Upload do Arquivo e, em seguida, selecione Selecionar Um para fazer upload do certificado como um arquivo no formato PEM.
  10. Ou selecione Colar Conteúdo e, em seguida, selecione a caixa de texto para colar o conteúdo do certificado diretamente.
  11. Selecione Próximo.
  12. Não é possível configurar a renovação automática para certificados que o serviço Certificates não gerencia. Selecione Próximo para continuar.
  13. Verifique se as informações do resumo estão corretas e selecione Criar Certificado.
  14. Será aberta a página Detalhes do certificado. Em Versões, localize o nome do certificado que você deseja exibir, vá para o menu Ações no final da linha e selecione Exibir Conteúdo. Para obter mais informações, consulte Exibindo Detalhes do Certificado.
  15. Selecione Fazer Download e Salvar o arquivo PEM do Certificado.
  16. Na página Detalhes do certificado, vá para a guia Informações do assunto e copie o Nome Comum para o certificado a ser usado na próxima etapa.

Etapa 5: Criar uma Instância Digital Twin que use um Certificado

Para autenticar um dispositivo para enviar dados, você pode criar uma instância de gêmeo digital usando o parâmetro --auth-id e o <certificate-OCID> criado na etapa anterior.

Use este comando e parâmetros para criar uma instância de gêmeo digital. Substitua o <common-name-for-the-certificate>. Substitua o <certificate-OCID> pelo OCID do Certificado do seu ambiente. Localize esses valores nos detalhes do Certificado. Para obter mais informações, consulte Exibindo Detalhes do Certificado:

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <certificate-OCID> --external-key <common-name-from-certificate-details>

Para obter uma lista completa de parâmetros da CLI, consulte oci iot digital-twin-instance create e Criando uma Instância Gêmea Digital para obter mais informações.

Etapa Opcional 6: Obter Detalhes da Instância de um Gêmeo Digital

Use este comando para exibir os detalhes de uma instância de gêmeo digital. A resposta contém o OCID da instância do gêmeo digital, o id de autenticação e a chave externa.
oci iot digital-twin-instance get --digital-twin-instance-id <digital-twin-instance-OCID>
Para obter mais informações, consulte Obtendo Detalhes da Instância de um Gêmeo Digital.

Etapa 7: Enviar Dados

Dependendo do seu cenário, você pode se conectar à instância de gêmeo digital usando MQTTS, HTTPS ou WebSocket. Para obter mais exemplos de cenários, consulte Conectando um dispositivo.

  • Usando o Curl

    Shells de estilo POSIX: Use este comando curl ao usar bash, zsh, Terminal macOS, Linux ou Git Bash no Windows para enviar uma mensagem de texto simples de amostra para testar a conexão. Substitua o device-cert.pem e o device-key.pem pelo caminho para os arquivos do seu ambiente.
    curl --cert /path/device-cert.pem --key /path/device-key.pem \
    -H "Content-Type: text/plain" \
    -d "sample data 1" \
    "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    Windows Powershell: Use este comando curl, substitua o device-cert.pem e o device-key.pem pelos valores do seu ambiente.

    curl.exe --cert /path/device-cert.pem --key /path/device-key.pem \
    -H "Content-Type: text/plain" \
    -d "sample data 1" \
    "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    Ao concluir a Etapa 3: Criar uma Instância Gêmea Digital, se você tiver definido o valor do parâmetro de chave externa com aspas, deverá incluir as aspas ao enviar os dados: "external-key". Para obter informações sobre melhores práticas, consulte Diagnosticando e Solucionando Problemas.

  • Use qualquer cliente MQTT para se inscrever em um tópico usando MQTTS. Este exemplo usa MQTTx.

    Para enviar dados de amostra e testar a conexão:

    1. Insira o host do dispositivo como host, por exemplo:
      mqtts://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
    2. Informe a porta: 8883
    3. ID do Cliente: your-client-ID
    4. Início da Limpeza: Verdadeiro
    5. Ative a alternância para ativar o TLS.
    6. Selecione a opção: CA ou certificados Autoassinados
    7. Informe o local do arquivo de certificado do cliente, na etapa 15 em Criar um Certificado Gerenciado Externamente: your-certificate.pem
    8. Informe o local do arquivo de chaves do cliente, na etapa 1 em Gerar uma Nova Chave Privada: your-private-key.pem
    9. Selecione Conexão.

      MQTTx

      Conecte-se usando MQTTx.

    10. Selecione Nova Assinatura para receber dados de um dispositivo.
    11. Informe o ponto final como o Tópico.
    12. Este exemplo mostra mensagens publicadas no tópico /endpoints/4321, no nível 1 do Quality of Service (QoS). tópico:
      {
        "pulse": 300,
        "s02": 400
      }
      {
        "test": 100
      }

      Inscreva-se em um tópico em MQTTx.

Etapa 7 Opcional: Monitorar os Dados IoT no APEX

Se você configurou o acesso para exibir seus dados no APEX e o dispositivo enviou dados brutos, poderá usar essa instrução SQL para exibir a resposta de dados brutos da instância do gêmeo digital no APEX.
select * from <domain-short-id-from-device-host>__IOT.RAW_DATA
where digital_twin_instance_id = '<digital-twin-instance-ocid>'