CryptoKey
The CryptoKey class in the 4D language encapsulates an asymmetric encryption key pair.
This class is available from the 4D class store.
Exemplo
The following sample code signs and verifies a message using a new ECDSA key pair, for example in order to make a ES256 JSON Web token.
// 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()
Histórico
| Versão | Mudanças |
|---|---|
| v18 R4 | Adicionado |
4D. CryptoKey.new( settings : Object ) : 4D. CryptoKey
| Parameter | Type | 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 |
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 | Type | Descrição |
|---|---|---|
| curve | texto | Name of ECDSA curve |
| pem | texto | PEM definition of an encryption key to load |
| size | integer | Size of RSA key in bits |
| type | texto | Type of the key: "RSA", "ECDSA", or "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
| Parameter | Type | Descrição | |
|---|---|---|---|
| message | Texto | -> | String de mensagens a decodificar utilizando options.encodingEncrypted e descifrar. |
| options | Objeto | -> | Opções de codificação |
| Resultado | Objeto | <- | Estado |
A função .decrypt() descifra o parâmetro message utilizando a chave private. O algoritmo utilizado depende do tipo da chave.
"RSA": um par de chaves RSA, utilizando settings.size como [.size](#size).
options
| Propriedade | Type | Descrição |
|---|---|---|
| hash | texto | Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512". |
| encodingEncrypted | texto | Encoding used to convert the message parameter into the binary representation to decrypt. Can be "Base64" or "Base64URL". Default is "Base64". |
| encodingDecrypted | texto | Encoding used to convert the binary decrypted message into the result string. Can be "UTF-8", "Base64", or "Base64URL". Default is "UTF-8". |
Resultado
A chave deveser do estilo RSA, o algoritmo é RSA-OAEP (ver RFC 3447).
| Propriedade | Type | Descrição |
|---|---|---|
| success | booleano | True if the message has been successfully decrypted |
| result | texto | Message decrypted and decoded using the options.encodingDecrypted |
| errors | collection | If success is false, may contain a collection of errors |
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ão | Mudanças |
|---|---|
| v18 R4 | Adicionado |
.encrypt( message : Text ; options : Object ) : Text
| Parameter | Type | Descrição | |
|---|---|---|---|
| message | Texto | -> | String de mensagens a codificar utilizando options.encodingDecrypted e encriptar |
| options | Objeto | -> | Opções de decodificação |
| Resultado | 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.
"RSA": um par de chaves RSA, utilizando settings.size como [.size](#size).
options
| Propriedade | Type | Descrição |
|---|---|---|
| hash | texto | Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512". |
| encodingEncrypted | texto | Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Default is "Base64". |
| encodingDecrypted | texto | Encoding used to convert the message parameter into the binary representation to encrypt. Can be "UTF-8", "Base64", or "Base64URL". Default is "UTF-8". |
Resultado
A chave deve ser do estilo RSA, o algoritmo é RSA-OAEP (ver RFC 3447).
.getPrivateKey()
Histórico
| Versão | Mudanças |
|---|---|
| v18 R4 | Adicionado |
.getPrivateKey() : Text
| Parameter | Type | Descrição | |
|---|---|---|---|
| Resultado | 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.
Resultado
O valor devolvido é a chave privada.
.getPublicKey()
Histórico
| Versão | Mudanças |
|---|---|
| v18 R4 | Adicionado |
.getPublicKey( ) : Text
| Parameter | Type | Descrição | |
|---|---|---|---|
| Resultado | 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.
Resultado
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
| Parameter | Type | 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 .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 privada.
options
| Propriedade | Type | Descrição |
|---|---|---|
| hash | texto | Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512". When used to produce a JWT, the hash size must match the PS@, ES@, RS@, or PS@ algorithm size |
| encodingEncrypted | texto | Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Default is "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 | Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Default is "Base64". |
Resultado
CryptoKey deve conter uma chave válida privada.
.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"
settings.size como .size.settings.curve como .curve. Lembre que chaves ECDSA não podem ser usadas para a criptografia mas só pela assinatura.settings.pem como .pem.
.verify()
Histórico
| Versão | Mudanças |
|---|---|
| v18 R4 | Adicionado |
.verify( message : Text ; signature : Text ; options : Object) : object
| Parameter | Type | 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 |
| Resultado | Objeto | <- | Estado da verificação |
Representação utf8 da string message.
CryptoKey deve conter uma chave válida publica.
options
| Propriedade | Type | Descrição |
|---|---|---|
| hash | texto | Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512". When used to produce a JWT, the hash size must match the PS@, ES@, RS@, or PS@ algorithm size |
| 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 | texto | Codificação utilizada para converter o parâmetro mensagem na representação binaria a decifrar. Pode ser "Base64", ou "Base64URL". Default is "Base64". |
Resultado
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).
| Propriedade | Type | Descrição |
|---|---|---|
| success | booleano | True se a assinatura corresponder com a mensagem |
| errors | collection | If success is false, may contain a collection of errors |