CryptoKey
The CryptoKey
class in the 4D language encapsulates an asymmetric encryption key pair.
This class is available from the 4D
class store.
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.
// 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( settings : Object ) : 4D.CryptoKey creates a new 4D.CryptoKey object encapsulating an encryption key pair |
.curve : Text normalised curve name of the key |
.decrypt( message : Text ; options : Object ) : Object decrypts the message parameter using the private key |
.encrypt( message : Text ; options : Object ) : Text encrypts the message parameter using the public key |
.getPrivateKey() : Text returns the private key of the CryptoKey object |
.getPublicKey() : Text returns the public key of the CryptoKey object |
.sign (message : Text ; options : Object) : Text signs the utf8 representation of a message string |
.size : Integer the size of the key in bits |
.type : Text name of the key type - "RSA", "ECDSA", "PEM" |
.verify( message : Text ; signature : Text ; options : Object) : object verifies the base64 signature against the utf8 representation of 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 |
result | 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. 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 | Defines the type of the key to create: |
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. É um objeto compartido e, portanto, pode ser utilizado por vários processos 4D simultaneamente.
.curve
História
Release | Mudanças |
---|---|
18 R4 | Adicionado |
.curve : Text
Defined only for ECDSA keys: the normalised curve name of the key. 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 | -> | Message string to be decoded using options.encodingEncrypted and decrypted. |
options | Object | -> | Opções de codificação |
Resultados | Object | <- | Estado |
The .decrypt()
function decrypts the message parameter using the private key. O algoritmo utilizado depende do tipo da chave.
The key must be a RSA key, the algorithm is RSA-OAEP (see RFC 3447).
opções
Propriedade | Tipo | Descrição |
---|---|---|
hash | text | Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512". |
encodingEncrypted | text | Encoding used to convert the message parameter into the binary representation to decrypt. 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
The function returns a status object with success
property set to true
if the message could be successfully decrypted.
Propriedade | Tipo | Descrição |
---|---|---|
success | boolean | True se a mensagem tiver sido decifrada com êxito |
result | text | Message decrypted and decoded using the options.encodingDecrypted |
errors | collection | If success is false , may contain a collection of errors |
In case the message couldn't be decrypted because it was not encrypted with the same key or algorithm, the status
object being returned contains an error collection in status.errors
.
.encrypt()
História
Release | Mudanças |
---|---|
18 R4 | Adicionado |
.encrypt( message : Text ; options : Object ) : Text
Parâmetro | Tipo | Descrição | |
---|---|---|---|
message | Text | -> | Message string to be encoded using options.encodingDecrypted and encrypted. |
options | Object | -> | Opções de decodificação |
Resultados | Text | <- | Message encrypted and encoded using the options.encodingEncrypted |
The .encrypt()
function encrypts the message parameter using the public key. O algoritmo utilizado depende do tipo da chave.
The key must be a RSA key, the algorithm is RSA-OAEP (see 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 | Encoding used to convert the message parameter into the binary representation to encrypt. 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 |
The .getPrivateKey()
function returns the private key of the CryptoKey
object in PEM format, or an empty string if none is available.
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 |
The .getPublicKey()
function returns the public key of the CryptoKey
object in PEM format, or an empty string if none is available.
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 |
---|---|
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 |
The .sign()
function signs the utf8 representation of a message string using the CryptoKey
object keys and provided options. It returns its signature in base64 or base64URL format, depending on the value of the options.encoding
attribute you passed.
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. Pass true when producing a JWT for PS@ algorithm |
encoding | text | Representation of provided signature. Possible values are "Base64" or "Base64URL". Por padrão é "Base64". |
Resultado
A representação utf8 da string message.
.size
História
Release | Mudanças |
---|---|
18 R4 | Adicionado |
.size : Integer
Defined only for RSA keys: the size of the key in bits. .
.type
História
Release | Mudanças |
---|---|
18 R4 | Adicionado |
.type : Text
Contains the name of the key type - "RSA", "ECDSA", "PEM" .
- "RSA": an RSA key pair, using
settings.size
as .size. - "ECDSA": an Elliptic Curve Digital Signature Algorithm key pair, using
settings.curve
as .curve. Lembre que chaves ECDSA não podem ser usadas para a criptografia mas só pela assinatura. - "PEM": a key pair definition in PEM format, using
settings.pem
as .pem.
.verify()
História
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 | -> | Signature to verify, in Base64 or Base64URL representation, depending on options.encoding value |
options | Object | -> | Opções de assinatura |
Resultados | Object | <- | Estado da verificação |
The .verify()
function verifies the base64 signature against the utf8 representation of message using the CryptoKey
object keys and provided options.
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. Pass true when verifying a JWT for PS@ algorithm |
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
The function returns a status object with success
property set to true
if message
could be successfully verified (i.e. the signature matches).
In case the signature couldn't be verified because it was not signed with the same message, key or algorithm, the status
object being returned contains an error collection in status.errors
.
Propriedade | Tipo | Descrição |
---|---|---|
success | boolean | True se a assinatura corresponder com a mensagem |
errors | collection | If success is false , may contain a collection of errors |