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 success
estabelecida 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 |