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

For a comprehensive overview of this class, please refer to the CryptoKey: encrypt, decrypt, sign, and verify! blog post.

Resumo


4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey creates a new `4D.CryptoKey` object encapsulating an encryption key pair
.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 : Object) : Text assina a representação utf8 de uma mensagem ** string
.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 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	->	Settings to generate or load a key pair
Resultados	4D.CryptoKey	<-	Objeto que contém um par de chaves de encriptação

The 4D.CryptoKey.new() function creates a new 4D.CryptoKey object encapsulating an encryption key pair, based upon the settings object parameter. It allows to generate a new RSA or ECDSA key, or to load an existing key pair from a PEM definition.

settings

Propriedade	Tipo	Descrição
type	text	Define 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.
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

The returned CryptoKey object encapsulates an encryption key pair. It is a shared object and can therefore be used by multiple 4D processes simultaneously.

Exemplo 1

A message is signed by a private key and the signature is verified by the corresponding public key. The following code signs and verifies a simple message signature.

Lado bob:

// Create the message
$message:="hello world"
Folder(fk desktop folder).file("message.txt").setText($message)

// Create a key
$type:=New object("type";"RSA")
$key:=4D.CryptoKey.new($type)

// Get the public key and save it
Folder(fk desktop folder).file("public.pem").setText($key.getPublicKey())

// Get signature as base64 and save it
Folder(fk desktop folder).file("signature").setText($key.sign($message;$type))

/*Bob sends the message, the public key and the signature to Alice*/

O lado Alice:

// Get message, public key & signature
$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()

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

// Verify signature
If ($key.verify($message;$signature;$type).success)
// The signature is valid

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.

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

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	<-	Message encrypted and encoded using the `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

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
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String mensagem a assinar
options	Object	->	Opções de assinatura
Resultados	Text	<-	Signature in Base64 or Base64URL representation, depending on "encoding" option

A função .sign() assina a representação utf8 de uma mensagem ** string 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	Representation 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

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
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String de mensagem utilizada para gerar 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