Edit

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.

 // Gerar um novo par de chaves ECDSA
$key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

  // Obter a assinatura como base64
$message:="hello world"
$signature:=$key.sign($message;New object("hash";"SHA256"))

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

Resumo

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

4D.CryptoKey.new()

Histórico

Versão	Mudanças
v18 R4	Adicionado

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

Parâmetros	Tipo		Descrição
settings	Objeto	->	Parâmetros para gerar ou carregar um par de chaves
result	4D.CryptoKey	<-	Objeto que contém um par de chaves de criptografia

|

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

settings

Propriedade	Tipo	Descrição
curve	texto	Nome da curva ECDSA
pem	text	Definição PEM de uma chave de cifrado a carregar
size	integer	Tamanho da chave RSA em bits
tipo	text	Tipo da chave: "RSA", "ECDSA" ou "PEM"

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ão	Mudanças
v18 R4	Adicionado

.curve : Text

Defined only for ECDSA keys: the curva normalizada nome da chave. Usually "prime256v1" for ES256 (default), "secp384r1" for ES384, "secp521r1" for ES512.

.decrypt()

Histórico

Versão	Mudanças
v18 R4	Adicionado

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

Parâmetros	Tipo		Descrição
message	Texto	->	String de mensagens a decodificar utilizando options.encodingEncrypted e descifrar.
options	Objeto	->	Opções de decodificação
Resultados	Objeto	<-	Estado

A função .decrypt() descifra o parâmetro message utilizando a chave private. O algoritmo utilizado depende do tipo da chave.

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

options

Propriedade	Tipo	Descrição
hash	texto	Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
encodingEncrypted	texto	Codificação utilizada para converter o parâmetro mensagem na representação binaria a decifrar. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
encodingDecrypted	text	Codificaçã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 função devolve um objeto "status" com a propriedade success definida como true se message puder ser descifrada com êxito.

Propriedade	Tipo	Descrição
success	booleano	True se a mensagem tiver sido decifrada com êxito
result	texto	Mensagem decifrado e decodificado utilizando options.encodingDecrypted
errors	collection	Se success for false, pode conter uma coleção de erros

Caso message não possa ser decifrado por não ter sido criptografado com a mesma chave ou algoritmo, o objeto status que se devolve conter uma coleção de erros em status.errors.

.encrypt()

Histórico

Versão	Mudanças
v18 R4	Adicionado

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

Parâmetros	Tipo		Descrição
message	Texto	->	String de mensagens a codificar utilizando options.encodingDecrypted e encriptar
options	Objeto	->	Opções de codificação
Resultados	Texto	<-	Mensagem criptografada e codificada utilizando options.encodingEncrypted

A função .encrypt() encrypts the message parâmetro usando a chave public. O algoritmo utilizado depende do tipo da chave.

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

options

Propriedade	Tipo	Descrição
hash	texto	Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
encodingEncrypted	texto	Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
encodingDecrypted	texto	Codificaçã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 criptografada.

.getPrivateKey()

Histórico

Versão	Mudanças
v18 R4	Adicionado

.getPrivateKey() : Text

Parâmetros	Tipo		Descrição
Resultados	Texto	<-	Chave privada em formato PEM

A função .getPrivateKey() devolve a chave privada do objeto CryptoKey em formato PEM, ou uma string vazia se não houver nenhuma disponível.

Resultados

O valor devolvido é a chave privada.

.getPublicKey()

Histórico

Versão	Mudanças
v18 R4	Adicionado

.getPublicKey( ) : Text

Parâmetros	Tipo		Descrição
Resultados	Texto	<-	Chave pública em formato PEM

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

Resultados

O valor devolvido é a chave pública.

---

.pem

Histórico

Versão	Mudanças
v18 R4	Adicionado

.pem : Text

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

.sign()

Histórico

Versão	Mudanças
v18 R4	Adicionado

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

Parâmetros	Tipo		Descrição
message	Texto	->	String mensagem a assinar
options	Objeto	->	Opções de assinatura
Resultado	Texto	<-	Assinatura em representação Base64 ou Base64URL, dependendo da opção "encoding"

A função .sign() assina a representação utf8 de uma string message utilizando as chaves de objeto CryptoKey e as options fornecidas. Devolve sua assinatura em formato base64 ou base64URL, dependendo do valor do atributo options.encoding que tiver passado.

CryptoKey deve conter uma chave válida privada.

options

Propriedade	Tipo	Descrição
hash	text	Algoritmo 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@
encodingEncrypted	text	Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
pss	booleano	Utiliza Probabilistic Signature Scheme (PSS). Ignorado se a chave não for uma chave RSA. Passa true ao produzir um JWT para o algoritmo PS@
encoding	texto	Representação que se utilizará para a assinatura de resultados. Valores possíveis: "Base64" ou "Base64URL". Por padrão é "Base64".

Resultados

Representação utf8 da string message.

.size

Histórico

Versão	Mudanças
v18 R4	Adicionado

.size : Integer

Definido só para chaves RSA: o tamanho da chave em bits. Normalmente 2048 padrão).

.type

Histórico

Versão	Mudanças
v18 R4	Adicionado

.type : Text

Nome do tipo da chave - "RSA", "ECDSA", "PEM"

"RSA": um par de chaves RSA, utilizando settings.size como .size.

"ECDSA": um par de chaves de Algoritmo de Firma Digital de Curva Elíptica, utilizando 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 de chaves em formato PEM usandosettings.pem como .pem.

.verify()

Histórico

Versão	Mudanças
v18 R4	Adicionado

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

Parâmetros	Tipo		Descrição
message	Texto	->	String de mensagem utilizada para gerar a assinatura
signature	Texto	->	Assinatura que vai ser verificada, em representação Base64 ou Base64URL, dependendo do valor de options.encoding
options	Objeto	->	Opções de assinatura
Resultados	Objeto	<-	Estado da verificação

A função .verify() 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 publica.

options

Propriedade	Type	Descrição
hash	text	Algoritmo 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@
pss	booleano	Utiliza Probabilistic Signature Scheme (PSS). Ignorado se a chave não for uma chave RSA. Passa true ao verficar um JWT para o algoritmo PS@
encoding	text	Representação de uma assinatura fornecida. Valores possíveis: "Base64" ou "Base64URL". Por padrão é "Base64".

Resultados

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

Caso a assinatura não possa ser confirmada porque message não foi assinada com a mesma chave ou algoritmo, o objeto status retornado terá um erro de coleção em status.errors.

Propriedade	Tipo	Descrição
success	booleano	True se a assinatura corresponder com a mensagem
errors	collection	Se success for false, pode conter uma coleção de erros