Skip to main content
Version: v19 R8 BETA

CryptoKey

A classe CryptoKey da linguagem 4D contém um par de chaves de cifrado assimétrico.

Esta classe está disponível na loja de classes de 4D.

Exemplo

O código abaixo de exemplo firma e verifica uma mensagem utilizando um novo par de chaves ECDSA, por exemplo para criar um token web JSON ES256.

 // Generate a new ECDSA key pair
$key:=4D. CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

// Get signature as base64
$message:="hello world"
$signature:=$key.sign($message;New object("hash";"SHA256"))

// Verify signature
$status:=$key.verify($message;$signature;New object("hash";"SHA256"))
ASSERT($status.success)

Resumo

4D. CryptoKey.new( settings : Object ) : 4D. CryptoKey    cria um novo objecto 4D.CryptoKey que encapsula um par de chaves de encriptação
.curve : Text    nome da curva normalizada da chave
.decrypt( message : Text ; options : Object ) : Object    decifra o parâmetro mensagem usando a chave privada
.encrypt( message : Text ; options : Object ) : Text    encripta o parâmetro mensagem utilizando a chave public
.getPrivateKey() : Text    devolve a chave privada do objecto CryptoKey
.getPublicKey( ) : Text    devolve a chave pública do objecto CryptoKey
.sign (message : Text ; options : Text) : Text    assina a representação utf8 de uma mensagem ** string
.size : Integer    o tamanho da chave em bits
.type : Text    name of the key type - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : object    verifica a assinatura base64 contra a representação utf8 de mensagem

4D. CryptoKey.new()

Histórico
VersãoMudanças
v18 R4Adicionado

4D. CryptoKey.new( settings : Object ) : 4D. CryptoKey

ParâmetrosTipoDescrição
settingsObjeto->Parâmetros para gerar ou carregar um par de chaves
result4D. CryptoKey<-Objeto que contém um par de chaves de criptografia

A função 4D.CryptoKey.new() cria um novo objecto 4D.CryptoKey que encapsula um par de chaves de encriptação, com base no parâmetro objecto settings. Permite gerar uma nova chave RSA o ECDSA, ou carregar um par de chaves existente desde uma definição PEM.

settings

PropriedadeTipoDescrição
typetextDefine o tipo da chave a criar:
  • "RSA": gera um par de chaves RSA usando .size como size.
  • "ECDSA": gera um par de chaves Elliptic Curve Digital Signature Algorithm, usando .curve como curve. Lembre que chaves ECDSA não podem ser usadas para a criptografia mas só pela assinatura.
  • "PEM": carrega uma definição de par de chaves em formato PEM, usando .pem.
  • curvetextNome da curva ECDSA
    pemtextDefinição PEM de uma chave de cifrado a carregar
    sizeintegerTamanho da chave RSA em bits

    CryptoKey

    O objeto CryptoKey devolvido encapsula um par de chaves de cifrado. É um objeto compartido e, portanto, pode ser utilizado por vários processos 4D simultaneamente.

    .curve

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .curve : Text

    Definido apenas para as chaves ECDSA: o nome da curva normalizada da chave. Normalmente "prime256v1" para ES256 (por defeito), "secp384r1" para ES384, "secp521r1" para ES512.

    .decrypt()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .decrypt( message : Text ; options : Object ) : Object

    ParâmetrosTipoDescrição
    messageText->String de mensagens a decodificar utilizando options.encodingEncrypted e descifrar.
    optionsObjeto->Opções de codificação
    ResultadosObjeto<-Estado

    A função .decrypt() decifra o parâmetro mensagem usando a chave privada. O algoritmo utilizado depende do tipo da chave.

    "RSA": um par de chaves RSA, utilizando settings.size como [.size](#size).

    options

    PropriedadeTipoDescrição
    hashtextAlgoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
    encodingEncryptedtextCodificação utilizada para converter o parâmetro mensagem na representação binaria a decifrar. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
    encodingDecryptedtextCodificação utilizada para converter a mensagem binário decifrado na string de resultados. Pode ser "UTF-8", "Base64" ou "Base64URL". Por padrão é "UTF-8".

    Resultados

    A chave deveser do estilo RSA, o algoritmo é RSA-OAEP (ver RFC 3447).

    PropriedadeTipoDescrição
    successbooleanTrue se a mensagem tiver sido decifrada com êxito
    resulttextMensagem decifrado e decodificado utilizando options.encodingDecrypted
    errorscollectionSe success for false, pode conter uma coleção de erros

    A função devolve um objeto "status" com a propriedade success definida como true se message puder ser descifrada com êxito.

    .encrypt()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .encrypt( message : Text ; options : Object ) : Text

    ParâmetrosTipoDescrição
    messageText->String de mensagens a codificar utilizando options.encodingDecrypted e encriptar
    optionsObjeto->Opções de decodificação
    ResultadosText<-Mensagem criptografada e codificada utilizando options.encodingEncrypted

    A função .encrypt() encripta o parâmetro mensagem utilizando a chave public. O algoritmo utilizado depende do tipo da chave.

    "RSA": um par de chaves RSA, utilizando settings.size como [.size](#size).

    options
    PropriedadeTipoDescrição
    hashtextAlgoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
    encodingEncryptedtextCodificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
    encodingDecryptedtextCodificação utilizada para converter o parâmetro mensagem na representação binaria a encriptar Pode ser "UTF-8", "Base64" ou "Base64URL". Por padrão é "UTF-8".

    Resultados

    O valor devolvido é uma mensagem encriptada.

    .getPrivateKey()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .getPrivateKey() : Text

    ParâmetrosTipoDescrição
    ResultadosText<-Chave privada em formato PEM

    A função .getPrivateKey() devolve a chave privada do objecto CryptoKey em formato PEM, ou uma string vazia se nenhum estiver disponível.

    Resultados

    O valor devolvido é a chave privada.

    .getPublicKey()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .getPublicKey( ) : Text

    ParâmetrosTipoDescrição
    ResultadosText<-Chave pública em formato PEM

    A função .getPublicKey() devolve a chave pública do objecto CryptoKey em formato PEM, ou uma string vazia se nenhum estiver disponível.

    Resultados

    O valor devolvido é a chave pública.


    .pem

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .pem : Text

    Definição PEM de uma chave de cifrado a carregar. Se a chave for uma chave privada, será deduzido dela a chave pública RSA ou ECDSA.

    .sign()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .sign (message : Text ; options : Text) : Text

    ParâmetrosTipoDescrição
    messageText->String mensagem a assinar
    optionsObjeto->Opções de assinatura
    ResultadosText<-Assinatura na representação Base64 ou Base64URL, dependendo da opção "codificação".

    A função .sign() assina a representação utf8 de uma mensagem * string utilizando o CryptoKey chaves-objecto e forneceu opções. Summary -->verifica a assinatura base64 contra a representação utf8 de message utilizando as chaves do objeto CryptoKey e as options* proporcionadas.

    CryptoKey deve conter uma chave válida privada.

    options

    PropriedadeTipoDescrição
    hashtextAlgoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512". Quando utilizar para produzir um JWT, o tamanho de hash deve coincidir com o tamanho do algoritmo PS@, ES@, RS@ ou PS@
    encodingEncryptedtextCodificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
    pssbooleanUtiliza Probabilistic Signature Scheme (PSS). Ignorado se a chave não for uma chave RSA. Passa true ao produzir um JWT para o algoritmo PS@
    encodingtextRepresentation of provided signature. Possible values are "Base64" or "Base64URL". Por padrão é "Base64".

    Resultados

    CryptoKey deve conter uma chave válida privada.

    .size

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .size : Integer

    Definido apenas para chaves RSA: o tamanho da chave em bits. Tipicamente 2048 (por defeito).

    .type

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .type : Text

    Contém name of the key type - "RSA", "ECDSA", "PEM" .

    • "RSA": um par de chaves RSA, usando settings.size como .size.
    • "ECDSA": um par de chaves de Algoritmos de Assinatura Digital de Curva Elíptica, usando settings.curve como .curve. Lembre que chaves ECDSA não podem ser usadas para a criptografia mas só pela assinatura.
    • "PEM": uma definição de par chave em formato PEM, usando settings.pem como .pem.

    .verify()

    Histórico
    VersãoMudanças
    v18 R4Adicionado

    .verify( message : Text ; signature : Text ; options : Object) : object

    ParâmetrosTipoDescrição
    messageText->String de mensagem utilizada para gerar a assinatura
    signatureText->Assinatura que vai ser verificada, em representação Base64 ou Base64URL, dependendo do valor de options.encoding
    optionsObjeto->Opções de assinatura
    ResultadosObjeto<-Estado da verificação

    A função .verify() verifica a assinatura base64 contra a representação utf8 de mensagem utilizando o CryptoKey chaves-objecto e forneceu opções.

    CryptoKey deve conter uma chave válida publica.

    options

    PropriedadeTipoDescrição
    hashtextAlgoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512". Quando utilizar para produzir um JWT, o tamanho de hash deve coincidir com o tamanho do algoritmo PS@, ES@, RS@ ou PS@
    pssbooleanUtiliza Probabilistic Signature Scheme (PSS). Ignorado se a chave não for uma chave RSA. Passa true ao verficar um JWT para o algoritmo PS@
    encodingtextEncoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Por padrão é "Base64".

    Resultados

    CryptoKey deve conter uma chave válida publica.

    A função devolve um objeto "status" com a propriedade successestabelecida para true se message puder ser verificada com êxito (ou seja, se a assinatura coincidir).

    PropriedadeTipoDescrição
    successbooleanTrue se a assinatura corresponder com a mensagem
    errorscollectionSe success for false, pode conter uma coleção de erros