Versão: 20

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.

Ver também

Para obter uma apresentação completa dessa classe, recomendamos que você leia a postagem do blog CryptoKey: criptografar, descriptografar, assinar e verificar!.

Resumo


4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey cria um objeto `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`
.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 (message : Text ; options : Object) : Text .sign (message : Blob ; options : Object) : Text assina a representação utf8 de um * $var:=OBJECT Get pointer(Object named;"tstart") * string ou Blob
.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 .verify( message* : Blob ; signature : Text ; options : Object) : Object verifica a assinatura base64 contra a representação utf8 de mensagem

4D. CryptoKey.new()

Histórico

Release	Mudanças
18 R4	Adicionado

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

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

A função 4D.CryptoKey.new() cria um objeto 4D.CryptoKey que encapsula um par de chaves de encriptação, com base no parâmetro 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
type	text	Define o tipo da chave a criar: "RSA": gera um par de chaves RSA, usando .size como tamanho. "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.
curve	text	Nome da curva ECDSA
pem	text	Definição PEM de uma chave de cifrado a carregar
size	integer	Tamanho 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.

Exemplo 1

Uma mensagem é assinada por uma chave privada e a assinatura é verificada pela chave pública correspondente. O código a seguir assina e verifica uma assinatura de mensagem simples.

Lado bob:

// Criar a mensagem
$message:="hello world"
Folder(fk desktop folder).file("message.txt").setText($message)

// Criar uma chave
$type:=New object("type"; "RSA")
$key:=4D.CryptoKey.new($type)

// Obtenha a chave pública e salve-a
Folder(fk desktop folder).file("public.pem").setText($key.getPublicKey())

// Obtenha a assinatura como base64 e salve-a
Folder(fk desktop folder).file("signature").setText($key.sign($message;$type))

/*Bob envia a mensagem, a chave pública e a assinatura para Alice*/

O lado Alice:

// Obter mensagem, chave pública e assinatura
$message:=Folder(fk desktop folder).file("message.txt").getText()
$publicKey:=Folder(fk desktop folder).file("public.pem").getText()
$signature:=Folder(fk desktop folder).file("signature").getText()

// Criar uma chave
$type:=New object("type"; "PEM"; "pem";$publicKey)
$key:=4D.CryptoKey.new($type)

// Verificar assinatura
If ($key.verify($message;$signature;$type).success)
// A assinatura é válida

End if

Exemplo 2

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)

.curve

Histórico

Release	Mudanças
18 R4	Adicionado

.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

Release	Mudanças
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String de mensagens a decodificar utilizando `options.encodingEncrypted` e descifrar.
options	Object	->	Opções de codificação
Resultados	Object	<-	Estado

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

A chave deve ser uma chave RSA, o algoritmo é RSA-OAEP (consulte RFC 3447).

options

Propriedade	Tipo	Descrição
hash	text	Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
encodingEncrypted	text	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

CryptoKey deve conter uma chave válida publica.

Propriedade	Tipo	Descrição
success	boolean	True se a mensagem tiver sido decifrada com êxito
resultado	text	Mensagem decifrado e decodificado utilizando `options.encodingDecrypted`
errors	collection	Se `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

Release	Mudanças
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String de mensagens a codificar utilizando `options.encodingDecrypted` e encriptar
options	Object	->	Opções de decodificação
Resultados	Text	<-	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.

A chave deve ser uma chave RSA, o algoritmo é RSA-OAEP (consulte RFC 3447).

options

Propriedade	Tipo	Descrição
hash	text	Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512".
encodingEncrypted	text	Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64".
encodingDecrypted	text	Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "UTF-8", "Base64" ou "Base64URL". Por padrão é "UTF-8".

Resultados

O valor devolvido é uma mensagem encriptada.

.getPrivateKey()

Histórico

Release	Mudanças
18 R4	Adicionado

.getPrivateKey() : Text

Parâmetro	Tipo		Descrição
Resultados	Text	<-	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

Release	Mudanças
18 R4	Adicionado

.getPublicKey() : Text

Parâmetro	Tipo		Descrição
Resultados	Text	<-	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

Release	Mudanças
18 R4	Adicionado

.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

Release	Mudanças
20 R8	Suporte de mensagem como Blob
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Texto OU Blob	->	Mensagem a assinar
options	Object	->	Opções de assinatura
Resultados	Text	<-	Assinatura na representação Base64 ou Base64URL, dependendo da opção "encoding"

A função .sign() assina a representação utf8 de um * $var:=OBJECT Get pointer(Object named;"tstart") * string ou Blob utilizando o CryptoKey chaves-objecto e forneceu opções. Devolve a sua assinatura no formato base64 ou base64URL, dependendo do valor do atributo options.encoding que passou.

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	boolean	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	text	Representação a ser usada para a assinatura do resultado. Possible values are "Base64" or "Base64URL". Por padrão é "Base64".

Resultados

A representação utf8 de message.

.size

Histórico

Release	Mudanças
18 R4	Adicionado

.size : Integer

Definido apenas para chaves RSA: o tamanho da chave em bits. .

.type

Histórico

Release	Mudanças
18 R4	Adicionado

.type : Text

Contém nome do tipo da chave - "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

Release	Mudanças
20 R8	Suporte de mensagem como Blob
18 R4	Adicionado

.verify( message : Text ; signature : Text ; options : Object) : Object
*.verify**( message : Blob ; signature : Text ; options : Object) : Object

Parâmetro	Tipo		Descrição
message	Texto OU Blob	->	Mensagem usada para produzir a assinatura
signature	Text	->	Assinatura que vai ser verificada, em representação Base64 ou Base64URL, dependendo do valor de `options.encoding`
options	Object	->	Opções de assinatura
Resultados	Object	<-	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

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@
pss	boolean	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	Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "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).

Se a assinatura não puder ser verificada por não ter sido assinada com a mesma message, chave ou algoritmo, o objecto status devolvido contém uma colecção de erros em status.errors.

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

Resumo​

4D. CryptoKey.new()​

settings​

CryptoKey​

Exemplo 1​

Exemplo 2​

.curve​

.decrypt()​

options​

Resultados​

.encrypt()​

options​

Resultados​

.getPrivateKey()​

Resultados​

.getPublicKey()​

Resultados​

.pem​

.sign()​

options​

Resultados​

.size​

.type​

.verify()​

options​

Resultados​

Resumo

4D. CryptoKey.new()

settings

CryptoKey

Exemplo 1

Exemplo 2

.curve

.decrypt()

options

Resultados

.encrypt()

options

Resultados

.getPrivateKey()

Resultados

.getPublicKey()

Resultados

.pem

.sign()

options

Resultados

.size

.type

.verify()

options

Resultados