KMFCryptoOperation - com escopo, global

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 12 min. de leitura

    • A classe KMFCryptoOperation fornece métodos para executar operações criptográficas usando um módulo criptográfico KMF ou um módulo de criptografia CLE.

    Para usar esta API, você já deve ter criado e configurado um módulo criptográfico Key Management Framework (KMF) ou um módulo de criptografia Column Level Encryption (CLE). O módulo deve ter uma ou mais especificações criptográficas e você deve criar ou importar sua chave associada. Para obter detalhes, consulte Módulos criptográficos.

    O objeto KMFCryptoOperation gerado usando esta API representa uma operação criptográfica, como uma Criptografia simétrica. Use o método KMFCryptoOperations() para criar este objeto, os métodos de construtor para definir propriedades no objeto e o método doOperation() para executar a operação.

    Você pode usar essa API em aplicações com escopo e globais. Você sempre deve especificar o namespace sn_kmf_ns ao chamar esta API.

    KMFCryptoOperation - KMFCryptoOperation(cadeia de caracteres cryptoModuleName, cadeia de caracteresoperationName)

    Cria um objeto KMFCryptoOperation para o módulo e a operação especificados.

    Esta API aproveita os métodos do construtor. Os métodos do construtor atualizam as propriedades no objeto KMFCryptoOperation, como a mudança do formato de saída desejado dos dados. Nem todos os métodos do construtor são válidos para todas as operações. Os métodos de construtor disponíveis para cada operação estão anotados na tabela de parâmetros abaixo.

    Os seguintes métodos de construtor são válidos para todos os tipos de operação:
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    cryptoModuleName Cadeia de caracteres Nome do módulo criptográfico do Key Management Framework (KMF) ou do módulo de criptografia Column Level Encryption (CLE) a ser usado. Você deve criar o módulo antes de chamar este método. Para obter detalhes, consulte Visão geral do módulo criptográfico.
    OperationName Cadeia de caracteres Nome da operação a ser executada.
    Valores válidos (sem distinção entre maiúsculas e minúsculas):
    • ASYMMETLIC_DECRYPTION: descriptografia de dados usando um algoritmo de chave assimétrica. Requer um módulo criptográfico KMF com uma finalidade criptográfica de descriptografia de dados assimétrica.
      • Métodos adicionais do construtor: withAdditionalInput()
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações do KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres
    • ASYMmetric_ENCRYPTION: criptografia de dados usando um algoritmo de chave assimétrica. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Criptografia de dados assimétrica.
      • Métodos adicionais do construtor: withAdditionalInput()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres . A saída também pode ser um objeto KMFEncryptionPayload. RSA e EC-IES são compatíveis com ambos. Para obter informações adicionais sobre o objeto KMFEncryptionPayload, consulte withAdditionalInput().
    • ASYMMETLIC_UNWRAPPING: desencapsulamento de chave usando um algoritmo de chave assimétrica. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Desencapsulamento de chave assimétrica.
      • Métodos adicionais do construtor: withAlgorithm()
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações do KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres
    • ASYMMETLIC_WRAPPING: encapsulamento de chave usando um algoritmo de chave assimétrica. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Encapsulamento de chave assimétrica.
      • Métodos adicionais do construtor: withAlgorithm(), withSysId()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres
    • MAC_GENERATION: geração de um código de autenticação de mensagem (MAC). Algoritmo de chave simétrica baseado em fornece integridade e autenticação de dados. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Autenticidade simétrica.
      • Métodos de construtor adicionais: Nenhum
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres
    • MAC_VERIFICATION: verificação de um MAC. Algoritmo de chave simétrica baseado em para fornecer integridade e autenticação de dados. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Autenticidade simétrica.
      • Métodos adicionais do construtor: withAdditionalInput()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: KMFNone - sem decodificação
      • Tipo de saída padrão: booliano
    • SIGNATURE_GENERATION: geração de uma assinatura digital. Algoritmo de chave assimétrica baseado em para fornecer integridade e autenticação de dados. Requer um módulo criptográfico KMF com uma finalidade criptográfica de geração de assinatura.
      • Métodos de construtor adicionais: Nenhum
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres
    • SIGNATURE_VERIFICATION: verificação de uma assinatura digital. Algoritmo de chave assimétrica baseado em para fornecer integridade e autenticação de dados. Requer um módulo criptográfico KMF com uma finalidade criptográfica de verificação de assinatura.
      • Métodos adicionais do construtor: withAdditionalInput()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: KMFNone - sem decodificação
      • Tipo de saída padrão: booliano
    • SYMmetric_ENCRYPTION: criptografia de dados usando um algoritmo de chave simétrica. Se o algoritmo não preservar a igualdade, somente a saída formatada será permitida. Requer um módulo criptográfico KMF com uma finalidade criptográfica de criptografia/descriptografia de dados simétrica.
      • Métodos de construtor adicionais: Nenhum
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres
    • SYMmetric_DECRYPTION: descriptografia de dados usando um algoritmo de chave simétrica. Se o algoritmo não preservar a igualdade, a entrada KMFBase64 será permitida. Requer um módulo criptográfico KMF com uma finalidade criptográfica de criptografia/descriptografia de dados simétrica.
      • Métodos de construtor adicionais: Nenhum
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações do KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres
    • SYMMETLIC_WRAPPING: encapsulamento de chave usando um algoritmo de chave simétrica. Se o algoritmo não preservar a igualdade, somente a saída formatada será permitida. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Encapsulamento/desencapsulamento de chave simétrica.
      • Métodos adicionais do construtor: withAlgorithm() e withSysId()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - Formatado de acordo com as especificações KMF
      • Tipo de saída padrão: cadeia de caracteres
    • SYMMETLIC_UNWRAPPING: desencapsulamento de chave usando um algoritmo de chave simétrica. Se o algoritmo não preservar a igualdade, a entrada KMFBase64 será permitida. Requer um módulo criptográfico KMF com uma finalidade criptográfica de Encapsulamento/desencapsulamento de chave simétrica.
      • Métodos adicionais do construtor: withAlgorithm()
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações do KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres

    Este exemplo instancia um objeto KMFCryptoOperation para que o módulo global.sj_cm execute uma operação de Criptografia simétrica. Você deve incluir o namespace para aplicações globais e com escopo.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION");

    Este exemplo mostra como especificar opções para atualizar o tipo de saída padrão e o formato de saída.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION")
  .withOutputType("STRING").withOutputFormat("FORMATTED");

var cipherText=op.doOperation("hi");

    Este exemplo mostra como executar uma operação de Criptografia assimétrica usando um Esquema de criptografia integrado (EC-IES). Observe que valores longos, como signature, foram truncados e substituídos por uma elipse para facilitar a leitura.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_ENCRYPTION")
.withInputFormat("KMFNONE")
.withOutputType("PAYLOAD");

var cipherText = op.doOperation("hi");

/*
cipherText contains an object similar to this JSON: {
  "signature": "pkg…",
  "ephemeral_key": "BDi…",
  "ciphertext": "afFS…"
}
*/

    Este exemplo mostra como executar uma operação de descriptografia assimétrica usando o EC-IES.

    var op = new 
sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput({
  "signature": "pkg… ",
  "ephemeral_key": "BDi…"
})
.withOutputFormat("KMFNONE");

var clearText = op.doOperation("afFS…");

    KMFCryptoOperation - doOperation(Object data)

    Executa a operação criptográfica definida pelo objeto KMFCryptoOperation atual nos dados fornecidos e retorna o resultado.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    dados Objeto Obrigatório, exceto se o método do construtor withSysId() tiver sido chamado anteriormente no objeto KMFCryptoOperation associado. Dados de entrada nos quais a operação criptográfica será executada.
    Tabela 3. Retorna
    Tipo Descrição
    Depende do tipo de operação.
    • MAC_VERIFICATION e SIGNATURE_VERIFICATION: booliano
    • Todos os outros: cadeia de caracteres
    		 Resultados de dados após executar a operação especificada no objeto KMFCryptoOperation associado.

    Este exemplo usa doOperation() para criar um MAC.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_GENERATION"); 
var data = "aGk="; 
var mac = op.doOperation(data);

    KMFCryptoOperation - withAdditionalInput(Object additionalInput)

    Define a entrada adicional necessária para executar a operação criptográfica.

    Por exemplo, durante uma verificação de código de autenticação de mensagem (MAC), use este método para passar o marcador MAC gerado. Da mesma forma, durante a verificação de assinatura, use-o para passar a assinatura. Você também pode usar este método para passar dados adicionais, um objeto KMFEncryptionPayload, ao executar uma operação assimétrica com uma cifra integrada, como Esquema de criptografia integrada de curva elíptica (EC-IES).

    Nota:
    A entrada adicional não precisa estar no mesmo formato definido atualmente no objeto KMFCryptoOperation.
    Tabela 4. Parâmetros
    Nome Tipo Descrição
    entradaadicional Cadeia de caracteres ou objeto Opcional, exceto para operações de descriptografia assimétrica ao usar EC-IES. Dados de entrada adicionais necessários para executar a operação criptográfica especificada no objeto KMFCryptoOperation.
    Formatos de cadeia de caracteres compatíveis:
    • FORMATADO: formatado de acordo com as especificações KMF (Key Management Framework).
    • KMFBASE64: codificado em Base64.

    Formato do objeto KMFEncryptionPayload:

    {
  "ciphertext": String,
  "derivation_secret": String,
  "ephemeral_key": String,
  "ephemeral_key_format": String,
  "signature": String
}
    textoDeEntrada.adicional.cifrado Cadeia de caracteres (Base64) Necessário para Descriptografia assimétrica, opcional para todas as outras operações.
    Valores válidos:
    • Se estiver usando um algoritmo RSA: texto cifrado RSA
    • Se estiver usando um algoritmo EC-IES: texto cifrado AES integrado

    Disponível na operação de Criptografia assimétrica quando o tipo de saída é definido como payload.
    entradaadicional.derivação_secret Cadeia de caracteres (Base64) Opcional, usado somente para operações de Criptografia assimétrica ou Descriptografia assimétrica com EC-IES. Segredo compartilhado a ser usado durante o processo de derivação de chave do esquema integrado.
    entradaadicional.efemera_chave Cadeia de caracteres (Base64) Necessário para a operação de descriptografia assimétrica ao usar EC-IES, opcional para todas as outras operações. Chave pública efêmera a ser usada durante o processo de acordo básico do esquema integrado.

    Disponível na operação de Criptografia assimétrica quando o tipo de saída é definido como payload.
    entradaadicional.efemero_chave_formato Cadeia de caracteres Opcional, usado somente para operações de Criptografia assimétrica ou Descriptografia assimétrica com EC-IES. Substitui o formato da chave pública representada pelo parâmetro ephemeral_key.
    Valores válidos:
    • x962
    • der
    entrada.adicional.assinatura Cadeia de caracteres (Base64) Necessário para a operação de descriptografia assimétrica com EC-IES, opcional para todas as outras. A assinatura do texto cifrado para validar usando o processo de verificação de assinatura do esquema integrado.

    Disponível na operação de Criptografia assimétrica quando o tipo de saída é definido como payload.
    Tabela 5. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withAdditionalInput() para adicionar uma assinatura baseada em cadeia de caracteres ao objeto KMFCryptoOperation.

    var signature = "John Doe";
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SIGNATURE_VERIFICATION")
  .withAdditionalInput(signature);

var value = GlideStringUtil.base64Encode("Text to encode"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

    Este exemplo usa withAdditionalInput() para adicionar uma assinatura e chave efêmera ao objeto KMFCryptoOperation. Observe que valores longos, como aqueles na chamada doOperation() e na descrição payload, foram truncados e substituídos por uma elipse para facilitar a leitura.

    var payload = new sn_kmf_ns.KMFEncryptionPayload();
payload.signature = "pkg...";
payload.ephemeral_key = " BDi...";
payload.ephemeral_key_format = "x962";

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput(payload)
  .doOperation("afFS...";

    KMFCryptoOperation - withAlgorithm(cadeia de caracteres "algoritmo")

    Define o algoritmo associado ao material da chave a ser encapsulado.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    algoritmo Cadeia de caracteres Algoritmo a ser usado.
    Valores válidos:
    • AES: tipo de chave simétrica
    • EC: tipo de chave assimétrica
    • HMAC: tipo de chave simétrica
    • RSA: tipo de chave assimétrica
    Tabela 7. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withAlgorithm() para mudar o algoritmo de criptografia usado para EC.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_WRAPPING").withAlgorithm("EC");
var value = GlideStringUtil.base64Encode("Sample key"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

    KMFCryptoOperation - withInputFormat(cadeia de caracteres inputFormat)

    Define o formato dos dados de entrada nos quais a operação criptográfica será realizada. Usa o formato especificado ao decodificar os dados.

    Tabela 8. Parâmetros
    Nome Tipo Descrição
    inputFormat Cadeia de caracteres Formato dos dados de entrada.
    Valores válidos:
    • FORMATADO: formatado de acordo com as especificações KMF (Key Management Framework).
    • KMFBASE64: codificado em Base64.
    • KMFNONE: sem codificação.

    Padrão: valor determinado pela operação especificada quando o objeto KMFCryptoOperation foi instanciado. Para obter mais informações, consulte KMFCryptoOperation - KMFCryptoOperation(cadeia de caracteres cryptoModuleName, cadeia de caracteresoperationName).
    Tabela 9. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withInputFormat() para mudar o formato de entrada para não ter codificação.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION").withInputFormat("KMFNone");
var result = op.doOperation("Text with no encoding"); // Pass in unencrypted String

    KMFCryptoOperation - withOutputFormat(cadeia de caracteres "outputFormat")

    Define o formato dos dados de saída que são retornados pela operação criptográfica. Usa o formato especificado ao codificar os dados.

    Tabela 10. Parâmetros
    Nome Tipo Descrição
    outputFormat Cadeia de caracteres Formato dos dados de saída.
    Valores válidos:
    • FORMATADO: formatado de acordo com as especificações KMF (Key Management Framework).
    • KMFBASE64: codificado em Base64.
    • KMFNONE: sem decodificação. Compatível somente com MAC_VERIFICATION e SIGNATURE_VERIFICATION.

    Padrão se este método não for chamado: valor determinado pela operação especificada quando o objeto KMFCryptoOperation foi instanciado. Para obter mais informações, consulte KMFCryptoOperation - KMFCryptoOperation(cadeia de caracteres cryptoModuleName, cadeia de caracteresoperationName).
    Tabela 11. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withOutputFormat() para definir o formato de saída da descriptografia como KMFNone (o padrão é KMFBase64).

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_DECRYPTION").withOutputFormat("KMFNone");
var clear_data = op.doOperation(<FORMATTED_data>); // Pass in default of FORMATTED data

    KMFCryptoOperation - withOutputType(cadeia de caracteres "outputType")

    Define o tipo de dados para os dados de saída retornados após a execução da operação criptográfica.

    Nota:
    Ao instanciar o objeto KMFCryptoOperation para operações MAC_VERIFICATION ou SIGNATURE_VERIFICATION, você também deve chamar este método, passando booliano, para definir o tipo de saída correto ou uma exceção será lançada ao executar a operação.
    Tabela 12. Parâmetros
    Nome Tipo Descrição
    tipo de saída Cadeia de caracteres Tipo de dados de saída.

    Nem todos os tipos de saída são aplicáveis a todas as operações. Para um tipo sem suporte, uma exceção é lançada.

    Valores válidos (sem distinção entre maiúsculas e minúsculas):
    • Cadeia de caracteres: não é válida para operações MAC_VERIFICATION ou SIGNATURE_VERIFICATION.
    • Booliano: válido somente para operações MAC_VERIFICATION ou SIGNATURE_VERIFICATION.
    • Carga: válido somente para a operação ASYMMETRIC_ENCRYPTION. Use este tipo de saída para EC-IES.
    Nota:
    Ao especificar uma saída de Carga útil, a saída do método doOperation() é um objeto KMFEncryptionPayload. Para obter mais informações sobre a estrutura deste objeto, consulte withAdditionalInput().

    Padrão: valor determinado pela operação, especificado quando o objeto KMFCryptoOperation foi instanciado. Para obter mais informações, consulte KMFCryptoOperation - KMFCryptoOperation(cadeia de caracteres cryptoModuleName, cadeia de caracteresoperationName).
    Tabela 13. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withOutputType() para definir o tipo de saída de MAC_VERIFICATION como booliano.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_VERIFICATION")
  .withOutputType("Boolean").withAdditionalInput(<MAC>);
var value = GlideStringUtil.base64Encode("Text to sign"); // Default input type is KMFBase64
var result = op.doOperation(String(value));

    KMFCryptoOperation - withSysId(cadeia de caracteres sysId)

    Define o sys_id da chave a ser encapsulado no objeto KMFCryptoOperation. Aplicável ao encapsulamento simétrico e assimétrico de chaves.

    Tabela 14. Parâmetros
    Nome Tipo Descrição
    sysId Cadeia de caracteres Sys_id da chave a ser encapsulada. Localizado na tabela Chave do módulo [sys_kmf_module_key].
    Tabela 15. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo usa withSysId() para definir a chave a ser encapsulada.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_WRAPPING").withSysId("0d06ce525b231010f86d1b341d81c777");
var wrappedKey = operation.doOperation(); // No need to pass data when using withSysId()