KMFCryptoOperation - com escopo, global

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 12 min. de leitura

    • A classe KMFCryptoOperation fornece métodos para executar operações criptográficas usando um módulo criptográfico Estrutura de gestão principal (KMF) ou um módulo de criptografia Criptografia de campo.

    Para usar esta API, você já deve ter criado e configurado um módulo criptográfico KMF ou um módulo de criptografia CLE. O módulo deve ter uma ou mais especificações criptográficas e você deve criar ou importar a 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 do construtor para definir propriedades no objeto e o método doOperation() para executar a operação.

    Você pode usar esta 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 caracteres "operationName")

    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 alterar o formato de saída desejado dos dados. Nem todos os métodos de construtor são válidos para todas as operações. Os métodos do construtor disponíveis para cada operação são anotados na tabela de parâmetros abaixo.

    Os seguintes métodos do construtor são válidos para todos os tipos de operação:
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    criptoMóduloNome Cadeia de caracteres Nome do módulo criptográfico KMF (Key Management Framework, Estrutura de gestão de chaves) ou módulo de criptografia Criptografia de campo 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.
    nomeDaoperação Cadeia de caracteres Nome da operação a ser executada.
    Valores válidos (sem distinção entre maiúsculas e minúsculas):
    • ASYMMETRIC_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 assimétrica de dados.
      • Métodos adicionais do construtor: withAdditionalInput()
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações 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 assimétrica de dados.
      • 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().
    • ASYMMETRIC_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 KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres
    • ASYMMETRIC_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 de construtor adicionais: 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_GNERATION: geração de um código de autenticação de mensagem (MAC). O 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 adicionais do construtor: 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 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_GNERATION: geração de uma assinatura digital. Algoritmo de chave assimétrica 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 adicionais do construtor: 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 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 adicionais do construtor: 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 adicionais do construtor: nenhum
      • Formato de entrada padrão: Formatado - Formatado de acordo com as especificações KMF
      • Formato de saída padrão: KMFBase64 - codificado em Base64
      • Tipo de saída padrão: cadeia de caracteres
    • SYMMETRIC_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 de construtor adicionais: 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
    • SYMMETRIC_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 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 o módulo global.sj_cm para executar 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 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 (dados do objeto)

    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. Retornos
    Tipo Descrição
    Depende do tipo de operação.
    • MAC_VERIFICATION e SIGNATURE_VERIFICATION: booliano
    • Todos os outros: cadeia de caracteres
    		 Os dados resultam após a execução da 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 no marcador de MAC gerado. Da mesma forma, durante a verificação de assinatura, use-a para aprovar 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 criptografia 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
    additionalInput 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 do Key Management Framework (KMF).
    • KMFBASE64: codificado em Base64.

    Formato do objeto KMFEncryptionPayload:

    {
  "ciphertext": String,
  "derivation_secret": String,
  "ephemeral_key": String,
  "ephemeral_key_format": String,
  "signature": String
}
    textoDeEntrada.adicional 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 está definido como payload.
    inputadicional.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.
    additionalInput.efemeral_key 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 está definido como payload.
    additionalInput.efemeral_key_format 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
    additionalInput.signature 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 está definido como payload.
    Tabela 5. Retornos
    Tipo Descrição
    Nenhum(a)

    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 uma 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 (algoritmo de cadeia de caracteres)

    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. Retornos
    Tipo Descrição
    Nenhum(a)

    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á executada. 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 do Key Management Framework (KMF).
    • KMFBASE64: codificado em Base64.
    • KMF_GLIDE_ENCRYPTER_FORMATTED: suporte a descriptografias de valores criptografados KMF e valores criptografados GlideEncrypter.
    • 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 caracteres "operationName").
    Tabela 9. Retornos
    Tipo Descrição
    Nenhum(a)

    Este exemplo usa withInputFormat() para alterar 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

    Este exemplo usa withInputFormat() para alterar o formato de entrada para KMF_GLIDE_ENCRYPTER_FORMATTED.

    var encryptOp = new sn_kmf_ns.KMFCryptoOperation("<module_name>", "SYMMETRIC_DECRYPTION")
 .withInputFormat("KMF_GLIDE_ENCRYPTER_FORMATTED")
 .withOutputFormat("KMFNone"); 

var clear_text = encryptOp.doOperation(<encrypted_text>);

    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 do Key Management Framework (KMF).
    • 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 caracteres "operationName").
    Tabela 11. Retornos
    Tipo Descrição
    Nenhum(a)

    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 o 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, 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 caracteres "operationName").
    Tabela 13. Retornos
    Tipo Descrição
    Nenhum(a)

    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.

    Tabela: chave do módulo [sys_kmf_module_key]
    Tabela 15. Retornos
    Tipo Descrição
    Nenhum(a)

    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()