KMFCryptoOperation - escopo, global

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 12 min. de leitura

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

    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 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 KMFCryptoOperations() método para criar este objeto, os métodos do construtor para definir propriedades no objeto e o. DoOperation() método para executar a operação.

    Você pode usar esta API em aplicações com escopo e globais. Você sempre deve especificar sn_kmf_ns Namespace 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 métodos do construtor. Os métodos do construtor atualizam as propriedades no objeto KMFCryptoOperation, como mudar o 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 do construtor disponíveis para cada operação sã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:
    Importante:
    Os valores de entrada base64 usados neste documento devem ser seguros para URL (contém somente caracteres A-Z, a-z, 0-9, traço ( - ) e sublinhado ( _ )).
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    CryptoModuleName Cadeia de caracteres Nome do módulo criptográfico do Key Management Framework (KMF) ou Criptografia de campo módulo de criptografia 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 (não diferenciam maiúsculas de minúsculas):
    • ASYMMETRIC_DECRIPTION: 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 de construtor adicionais: ComEntrada Adicional()
      • 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 assimétrica de dados.
      • Métodos de construtor adicionais: ComEntrada Adicional()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - formatado de acordo com as especificações do KMF
      • Tipo de saída padrão: Cadeia de caracteres .A saída também pode ser um KMFEncryptionPayload objeto. RSA e EC-IES são compatíveis com ambos. Para obter informações adicionais sobre o objeto KMFEncryptionPayload, consulte ComEntrada Adicional() .
    • 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 de construtor adicionais: Com Algoritmo()
      • 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_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: Com Algoritmo() , WitSYSID()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - formatado de acordo com as especificações do 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 do KMF
      • Tipo de saída padrão: Cadeia de caracteres
    • MAC_VERIFICATION: Verificação de um MAC. Algoritmo de chave simétrica baseado 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 de construtor adicionais: ComEntrada Adicional()
      • 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 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 do KMF
      • Tipo de saída padrão: Cadeia de caracteres
    • SIGNATURE_VERIFICATION: Verificação de uma assinatura digital. Algoritmo de chave assimétrica baseado 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 de construtor adicionais: ComEntrada Adicional()
      • 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 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 do KMF
      • Tipo de saída padrão: Cadeia de caracteres
    • SYMMETRIC_DECRIPTION: Descriptografia de dados usando um algoritmo de chave simétrica. Se o algoritmo não for preservação de 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
    • SYMMETRIC_WRAPPING: Encapsulamento de chave usando um algoritmo de chave simétrica. Se o algoritmo não preservar 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: Com Algoritmo() e. WitSYSID()
      • Formato de entrada padrão: KMFBase64 - codificado em Base64
      • Formato de saída padrão: Formatado - formatado de acordo com as especificações do 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 for preservação de 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 de construtor adicionais: Com Algoritmo()
      • 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 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 integrada (EC-IES). Valores longos, como signatureforam 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 Necessário, exceto se WitSYSID() O método do construtor foi chamado anteriormente no objeto KMFCryptoOperation associado. Dados de entrada nos quais executar a operação criptográfica.
    Tabela 3. Retornos
    Tipo Descrição
    Depende do tipo de operação.
    • MAC_VERIFICATIONe. SIGNATURE_VERIFICATION: Booliano
    • Todos os outros: Cadeia de caracteres
    		 Resultados de dados 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 MAC (Message Authentication Code, código de autenticação de mensagem), 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 esse 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 no momento no objeto KMFCryptoOperation.
    Tabela 4. Parâmetros
    Nome Tipo Descrição
    AdditionalEntradas 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
}
    EntoTexto.cifhertext 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 Criptografia assimétrica quando o tipo de saída está definido como payload.
    additionalInput.derivation_secret Cadeia de caracteres (Base64) Opcional, usado somente para as 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.efememeral_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 Criptografia assimétrica quando o tipo de saída está definido como payload.
    Entradas adicionais.efêmero_key_format Cadeia de caracteres Opcional, usado somente para as operações de Criptografia assimétrica ou Descriptografia assimétrica com EC-IES. Substitui o formato da chave pública representada pelo ephemeral_keyparâmetro.
    Valores válidos:
    • x962
    • der
    Entrada.assinatura adicional Cadeia de caracteres (Base64) Necessário para a operação de descriptografia assimétrica com EC-IES, opcional para todos os outros. A assinatura do texto cifrado a ser validada usando o processo de verificação de assinatura do esquema integrado.

    Disponível na operação Criptografia assimétrica quando o tipo de saída está definido como payload.
    Tabela 5. Retornos
    Tipo Descrição
    Nenhum(a)

    Este exemplo usa ComEntrada Adicional() 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 ComEntrada Adicional() Para adicionar uma assinatura e uma chave efêmera ao objeto KMFCryptoOperation. Observe que valores longos, como aqueles em DoOperation() ligue para e. payloaddescrição, foram truncadas e substituídas 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 Com Algoritmo() 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 de dados para os 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 do Key Management Framework (KMF).
    • KMFBASE64: Codificado em base64.
    • KMF_GLIDE_ENCRYPTER_FORMATTED: Oferece suporte a descrições de valores criptografados KMF e valores criptografados pelo GlideEncrypter.
    • KMFNONE: Sem codificaçã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 ComInputFormat() 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

    Este exemplo usa ComInputFormat() Para mudar 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 de dados dos dados de saída 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:
    Quando você instanciar o objeto KMFCryptoOperation para MAC_VERIFICATIONou SIGNATURE_VERIFICATIONoperações, você também deve chamar esse método, passando booliano, para definir o tipo de saída correto ou uma exceção será lançada quando você executar a operação.
    Tabela 12. Parâmetros
    Nome Tipo Descrição
    OutputType 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 incompatível, uma exceção é lançada.

    Valores válidos (não diferenciam maiúsculas de minúsculas):
    • Cadeia de caracteres: Não é válido para MAC_VERIFICATIONou SIGNATURE_VERIFICATIONoperações.
    • Booliano: Válido somente para MAC_VERIFICATIONou SIGNATURE_VERIFICATIONoperações.
    • Carga: Válida somente para ASYMMETRIC_ENCRYPTIONoperação. Use este tipo de saída para EC-IES.
    Nota:
    Ao especificar uma saída de Carga , a saída do DoOperation() O método é um objeto KMFEncryptionPayload. Para obter mais informações sobre a estrutura deste objeto, consulte ComEntrada Adicional() .

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