Aplicativos personalizados

O uso do HPCS por aplicativos personalizados ocorre quando o código personalizado ou os aplicativos ISV fazem uso direto do HPCS.

A pesquisa do uso do HPCS por aplicativos personalizados é uma tarefa que você precisa realizar com a ajuda de eventos de rastreamento de atividades do HPCS, pesquisa de código e outros métodos.

Pesquise o uso dos seguintes termos:

• Referências a nomes de host que contêm hs-crypto
• API REST DO HPCS
• GREP11
• Plug-ins HPCS CLI

Além disso, pesquise o uso do HPCS por meio da biblioteca HPCS PKCS11:

• HPCS PKCS #11

Além disso, pesquise o uso por meio de SDKs de clientes:

• Cliente Keyprotect-go
• Cliente Keyprotect-python
• Cliente Keyprotect-java
• Cliente Keyprotect-nodejs
• pedra vermelha
• hpcs-grep11

Pesquise identidades IAM com acesso ao HPCS, principalmente IDs de serviço e perfis confiáveis, e identidades de usuário menos comuns. Qualquer identidade com funções cujo escopo seja o serviço, a instância, o chaveiro ou a chave do HPCS é um forte indicador do possível uso de aplicativos personalizados.

IBM Cloud serviços e software

Para identificar os serviços e o software IBM Cloud que estão usando HPCS, siga esta abordagem recomendada:

1. Comece com o Key Usage Reporter (KUR)- A ferramenta Key Usage Reporter(KUR) é o ponto de partida recomendado. Ele examina suas contas IBM Cloud e gera um relatório abrangente dos recursos que fazem referência às chaves HPCS, que são agrupadas por serviço e chave.

2. Referência cruzada com o rastreamento de atividades- Analise os eventos de rastreamento de atividades do HPCS durante a maior janela de tempo disponível para identificar os serviços que realizaram operações criptográficas. A ferramenta Key Usage Reporter(KUR) pode processar arquivos de registro de auditoria de rastreamento de atividades, produzindo resumos em CSV que ajudam a identificar a utilização do HPCS.

Verificação da existência de CRKs

Use o script Bash a seguir para contar o número total de CRKs em todos os estados de uma instância do HPCS.

Certifique-se de que esteja conectado a IBM Cloud por meio da CLI de IBM Cloud.

# count the total number of CRKs in all states
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=0,1,2,3,5&extractable=false" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of CRKs in all states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Substitua HPCS_ADDR e HPCS_INSTANCE_ID por valores válidos para cada instância HPCS. Você pode encontrar o endpoint da instância para HPCS e o ID da instância no console da interface do usuário IBM Cloud para a instância específica.

A saída é semelhante ao exemplo a seguir:

Total number of CRKs in all states: 11

Se houver zero CRKs em todas as instâncias do HPCS, a migração de CRKs não será necessária.

Verifique a contagem de CRKs nos estados Ativo (1) e Desativado (Expirado) (3) usando o script a seguir. Somente os CRKs nos estados Ativo (1) ou Desativado (Expirado) (3) podem ser usados para operações criptográficas, como empacotar, desempacotar e empacotar novamente. Um CRK desativado (3) é compatível com o desdobramento e o redobramento, mas não com o desdobramento.

# count the total number of CRKs in Active (1) or Deactivated (Expired) (3) states
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=1,3&extractable=false" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of CRKs in Active (1) or Deactivated (Expired) (3) states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Se houver zero CRKs nos estados Ativo (1) ou Desativado (Expirado) (3) em todas as instâncias do HPCS, nenhum CRK estará disponível para operações criptográficas. No entanto, o HPCS ainda pode estar em uso. Os recursos ou aplicativos ainda podem ser configurados para fazer referência a CRKs em outros estados. Qualquer tentativa de realizar operações criptográficas com esses CRKs falha.

Interpretação das contagens de CRK:

Você pode obter o CRN completo dos HPCS CRKs usando a CLI IBM Cloud kp keys comando.

O exemplo a seguir lista os CRKs em todos os estados:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
ibmcloud kp keys --instance-id fadedbee-0000-0000-0000-1234567890ab --crn --key-type root-key --key-states active,suspended,deactivated,destroyed --number-of-keys 5000

Substitua KP_TARGET_ADDR por valores válidos para cada instância HPCS. Você pode encontrar o endpoint da instância para HPCS no console da interface do usuário IBM Cloud para a instância específica.

• O comando lista os CRKs em todos os estados, incluindo os estados Suspenso (Desativado) e Destruído (excluído suavemente).
• Não é permitido o uso criptográfico ativo de CRKs nos estados Suspenso (Desativado) e Destruído (excluído suavemente), mas os CRKs nesses estados ainda podem ser referenciados pelos recursos do site IBM Cloud ou pelo código personalizado.
• É possível mover os CRKs dos estados Suspenso (Desativado) e Destruído (excluído suavemente) para o estado Ativo.
• O comando pode listar até 5.000 CRKs por vez. A paginação pode ser necessária para listar todos os CRKs.

Migração de chaves raiz do cliente (CRKs) em aplicativos personalizados

Aplicativos personalizados podem migrar CRKs para Key Protect Dedicated, reenquadrando a chave de criptografia de dados (DEK) que é protegida pelo HPCS.

O processo de migração envolve as seguintes etapas:

• Desembrulhe a chave de criptografia de dados (DEK) do HPCS.
• Envolva o DEK com Key Protect Dedicated.
• Gerar uma nova chave de criptografia de dados agrupados (WDEK).
• Use o novo WDEK para operações criptográficas subsequentes.

Em todos os casos, os aplicativos personalizados devem:

• Use um endpoint diferente. Uma instância do Key Protect Dedicated tem um endpoint específico para essa instância.
• Use um ID de chave diferente.
• Use uma identidade IAM, provavelmente uma ID de serviço, que permita o acesso ao Key Protect Dedicated no nível apropriado. Podem ser necessárias novas políticas de IAM voltadas para Key Protect Dedicated.

Para obter mais informações sobre a API Key Protect, consulte a referência da API Key Protect.

Migração de chaves raiz do cliente (CRKs) em serviços e software do site IBM Cloud

Alguns serviços IBM Cloud e o software IBM que se integram ao HPCS podem participar de um fluxo de trabalho automatizado de migração de CRK para o Key Protect Dedicated. Esse fluxo de trabalho é baseado em intenções de migração e eventos de sincronização do ciclo de vida das chaves e minimiza a interrupção, preservando a continuidade criptográfica.

Etapa 4: Criar a intenção de migração

Use a Key Migration Tool(CRKM) para criar uma intenção de migração em HPCS_key_1 que faça referência ao CRK de destino KP_D_key_1. A ferramenta CRKM aceita um arquivo CSV que contém pares de CRNs HPCS CRK de origem e CRNs CRK dedicados de destino Key Protect, o que possibilita a criação de intenções de migração em massa.

Depois que a intenção de migração é criada, o HPCS emite eventos de sincronização que notificam os serviços associados sobre a solicitação de migração.

Etapa 5: Executar a sincronização

Para alguns serviços (por exemplo, IBM Cloud Databases, Messages for RabbitMQ, Kubernetes e OpenShift ), mais eventos de sincronização devem ser explicitamente acionados alguns minutos após a criação da intenção. Use o comando de sincronização da ferramenta CRKM para acionar esses eventos.

Você pode executar o comando sync a qualquer momento para tentar novamente migrações incompletas.

Etapa 6: Acompanhar o andamento da migração

Use o comando Status da ferramenta CRKM para verificar o progresso da migração. A ferramenta informa as contagens de associação para o CRK HPCS de origem e o CRK dedicado de destino Key Protect. Como os serviços concluem a migração:

• O número de associações em HPCS_key_1 diminui.
• O número de associações em KP_D_key_1 aumenta.

Para Event Streams, a migração pode levar até um dia útil. Para outros serviços, espera-se que a migração seja concluída em menos de quatro horas.

Sobre a ferramenta de migração de chaves (CRKM)

A Key Migration Tool(CRKM) é uma ferramenta CLI que oferece suporte às seguintes operações:

• Status: Relata o progresso da migração mostrando as contagens de associação para CRKs de origem e destino em todos os pares de CRKs.
• Verificação de autenticidade: Verifica se as políticas de autorização de IAM necessárias estão em vigor para cada serviço registrado antes da migração. Relatórios de políticas correspondentes e ausentes com modelos acionáveis.
• Create (Criar ): Cria intenções de migração em massa a partir de um arquivo CSV de pares CRK CRN de origem e destino.
• Sincronização: Aciona eventos de sincronização para solicitar que os serviços processem a intenção de migração. Pode ser executado várias vezes para tentar novamente migrações incompletas.
• Excluir: Remove a intenção de migração de uma ou mais chaves de origem.

A ferramenta CRKM é necessária para a migração automatizada de CRKs e funciona com a ferramenta KUR, que lida com a descoberta e a geração de relatórios.

Verificação da existência de chaves padrão

Use o script bash a seguir para contar o número total de chaves padrão em todos os estados de chave padrão válidos, em cada instância do HPCS.

Certifique-se de que esteja conectado a IBM Cloud por meio da CLI de IBM Cloud.

# count the total number of Standard keys in all states
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=1,5&extractable=true" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of Standard keys in all states: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Substitua HPCS_ADDR e HPCS_INSTANCE_ID por valores válidos para cada instância HPCS. Você pode encontrar o endpoint da instância para HPCS e o ID da instância no console da interface do usuário IBM Cloud para a instância específica.

A saída é semelhante ao exemplo a seguir:

Total number of Standard keys in all states: 4

Se a saída for uma linha vazia, faça login em IBM Cloud por meio da CLI de IBM Cloud novamente.

Se não houver nenhuma chave padrão em todas as instâncias do HPCS, a migração da chave padrão não será necessária.

Verifique a contagem de chaves padrão no estado Destroyed (5) usando o script a seguir.

# count the total number of Standard keys in Destroyed (5) state.
HPCS_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
HPCS_INSTANCE_ID=fadedbee-0000-0000-0000-1234567890ab
AUTH_HEADER="${AUTH_TOKEN:-$(jq -r .IAMToken ~/.bluemix/config.json)}"
header="$(curl -i -k -s --head \
  "${HPCS_ADDR}/api/v2/keys?state=5&extractable=true" \
  -H "authorization: ${AUTH_HEADER}" \
  -H "bluemix-instance: ${HPCS_INSTANCE_ID}" \
  -H "prefer: return=representation" \
| grep '^Key-Total:' \
| tr -d '\r')"
if [ -n "$header" ]; then
  total="${header#Key-Total: }"
  echo "Total number of Standard keys in Destroyed (5) state: $total"
else
  echo "Error: Key-Total header not found. Try logging into IBM Cloud again. Check endpoint, auth token, or permissions." >&2
fi

Se todas as teclas padrão estiverem no estado Destruído (5) (soft deleted), não há garantia de ausência de uso. Um recurso IBM Cloud ou aplicativo personalizado ainda pode fazer referência à chave. Nesse caso, espera-se que as operações falhem na próxima tentativa de recuperação de material-chave.

As chaves padrão podem existir somente nos estados Ativo (1) ou Destruído (5). Outros estados-chave se aplicam apenas a CRKs.

Você pode obter o CRN completo das chaves padrão HPCS usando a CLI IBM Cloud kp keys comando.

O exemplo a seguir lista as chaves padrão nos estados possíveis:

export KP_TARGET_ADDR=https://fadedbee-0000-0000-0000-1234567890ab.api.us-south.hs-crypto.appdomain.cloud
ibmcloud kp keys --instance-id fadedbee-0000-0000-0000-1234567890ab --crn --key-type standard-key --key-states active,destroyed --number-of-keys 5000

Substitua KP_TARGET_ADDR por valores válidos para cada instância HPCS. Você pode encontrar o endpoint da instância para HPCS no console da interface do usuário IBM Cloud para a instância específica.

• O comando pode listar até 5.000 teclas padrão por vez. A paginação pode ser necessária para listar todas as chaves padrão.

keysvrmgr show -t hpcs
hdcryptmgr showlv <lvname> -v
hdcryptmgr showpv <pvname> -v

Validar se o HPCS não está mais em uso

Após a migração, inspecione os eventos de rastreamento de atividades do HPCS para confirmar que nenhuma operação é executada em instâncias do HPCS.

Revisar eventos durante a maior janela de retenção disponível.

Se os eventos de rastreamento de atividade indicarem uso contínuo:

1. Identifique o serviço ou a carga de trabalho responsável pelo uso.
2. Verifique se o recurso suporta a migração de CRK usando a intenção de migração.
3. Conclua ou tente novamente a migração para esse uso antes de prosseguir.

A falta de eventos de rastreamento de atividades não prova conclusivamente a ausência de uso. Alguns serviços e aplicativos personalizados usam chaves com pouca frequência ou apenas durante eventos de ciclo de vida, como reinicialização, restauração ou failover.

Desativar gradualmente os CRKs HPCS migrados

Depois de ter certeza de que CRKs HPCS específicos não são mais necessários, você pode desativá-los.

Recomenda-se a desativação dos CRKs antes da exclusão porque:

• Todas as operações criptográficas restantes falham imediatamente com um erro claro.
• As chaves desativadas podem ser reativadas rapidamente se forem descobertas dependências inesperadas.
• É fornecido um mecanismo de reversão seguro durante a validação.

Um marco recomendado é garantir que todos os HPCS CRKs que foram migrados com sucesso estejam no estado Desativado.

Os CRKs no estado Desativado podem ser reativados a qualquer momento e não bloqueiam permanentemente a correção.

Marcos finais e considerações sobre o descomissionamento

A exclusão de CRKs e chaves padrão HPCS é tecnicamente possível. No entanto, é preciso ter cautela ao abordar a exclusão:

• As chaves excluídas podem ser recuperadas somente por um período limitado após a exclusão.
• Depois que a janela de recuperação expirar, a exclusão será permanente.
• A recuperação se torna cada vez mais difícil à medida que o tempo passa e as cargas de trabalho evoluem.

Por esses motivos, não é necessário excluir as chaves HPCS como parte da migração.

Uma abordagem conservadora e recomendada é:

1. Deixe as instâncias HPCS e os CRKs desativados.
2. Não os reative ou modifique após a validação.

Essa abordagem minimiza o risco e garante que a migração criptográfica seja concluída com êxito.

As suas responsabilidades

Você é responsável por:

• Verificação de que todo o uso do HPCS foi interrompido
• Validação do comportamento de aplicativos e serviços após a migração

Prossiga com as atividades de desativação somente quando tiver certeza de que o HPCS não é mais necessário para nenhuma carga de trabalho.