CryptoKey

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

Essa classe está disponível no "class store" de 4D.

Veja também

Para obter uma visão geral abrangente dessa classe, consulte a postagem do blog CryptoKey: criptografar, descriptografar, assinar e verificar!.

Resumo

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey cria um novo objeto 4D.CryptoKey que encapsula um par de chaves de criptografia
.curve : Text nome da curva normalizada da chave
.decrypt( message : Text ; options : Object ) : Object descriptografa o parâmetro message usando a chave privada
.encrypt( message : Text ; options : Object ) : Text criptografa o parâmetro message usando a chave pública
.getPrivateKey() : Text retorna a chave privada do objetoCryptoKey\
.getPublicKey() : Text retorna a chave pública do objeto 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 uma string message ou Blob
.size : Integer o tamanho da chave em bits
.type : Text do tipo de chave - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : Object *.verify**( message : Blob ; signature : Text ; options : Object) : Object verifica a assinatura base64 em relação à representação utf8 da message

4D. CryptoKey.new()

História

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 novo objeto 4D.CryptoKey que encapsula um par de chaves de criptografia, 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.

parâmetros

Propriedade	Tipo	Descrição
type	text	Define o tipo de chave a ser criada: "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 curva. Note que chaves ECDSA não podem ser usadas para criptografia, mas apenas para assinatura. "PEM": carrega uma definição de par chave no 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ória

Release	Mudanças
18 R4	Adicionado

.curve : Text

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

.decrypt()

História

Release	Mudanças
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String de mensagens a ser decodificada usando options.encodingEncrypted e descriptografada.
options	Object	->	Opções de codificação
Resultados	Object	<-	Estado

A função .encrypt() criptografa o parâmetro message usando a chave pública. O algoritmo utilizado depende do tipo da chave.

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

opções

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 message 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".

Resultado

A função retorna um objeto status com a propriedade success definida como true se a mensagem puder ser descriptografada com êxito.

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

Caso a mensagem não possa ser descriptografada porque não foi criptografada com a mesma chave ou algoritmo, o objeto status que está sendo retornado contém uma coleção de erros em status.errors.

.encrypt()

História

Release	Mudanças
18 R4	Adicionado

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

Parâmetro	Tipo		Descrição
message	Text	->	String de mensagens a ser codificada utilizando options.encodingDecrypted e criptografada.
options	Object	->	Opções de decodificação
Resultados	Text	<-	Mensagem criptografada e codificada utilizando options.encodingEncrypted

A função .decrypt() descriptografa o parâmetro message 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).

opções

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 usada para converter o parâmetro message na representação binária a ser criptografada. Pode ser "UTF-8", "Base64" ou "Base64URL". Por padrão é "UTF-8".

Resultado

O valor devolvido é uma mensagem encriptada.

.getPrivateKey()

História

Release	Mudanças
18 R4	Adicionado

.getPrivateKey() : Text

Parâmetro	Tipo		Descrição
Resultados	Text	<-	Chave privada em formato PEM

A função ’.getPrivateKey()retorna a chave privada do objetoCryptoKey` no formato PEM ou uma cadeia de caracteres vazia se não houver nenhuma disponível.

Resultado

O valor devolvido é a chave privada.

.getPublicKey()

História

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() retorna a chave pública do objeto CryptoKey no formato PEM ou uma cadeia de caracteres vazia se não houver nenhuma disponível.

Resultado

O valor devolvido é a chave pública.

---

.pem

História

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ória

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 uma string message ou Blob usando as chaves do objeto CryptoKey e as opções fornecidas. Ele retorna sua assinatura no formato base64 ou base64URL dependendo do valor do atributo options.encoding que você passou.

A CryptoKey deve conter uma chave privada válida.

opções

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. Passe 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".

Resultado

A representação utf8 de mensagem.

.size

História

Release	Mudanças
18 R4	Adicionado

.size : Integer

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

.type

História

Release	Mudanças
18 R4	Adicionado

.type : Text

Contém o nome do tipo de chave - "RSA", "ECDSA", "PEM" .

• "RSA": um par de chaves RSA, usando settings.size como .size.
• "ECDSA": um par de chaves Elliptic Curve Digital Signature Algorithm, 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ória

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 em relação à representação utf8 da message usando as chaves do objeto CryptoKey e as options fornecidas.

A CryptoKey deve conter uma chave pública válida.

opções

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

Resultado

A função devolve um objeto status com a propriedade success estabelecida 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