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
.
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.
// Gerar um novo par de chaves ECDSA
$key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))
// Obter a assinatura como base64
$message:="hello world"
$signature:=$key.sign($message;New object("hash";"SHA256"))
// Verificar assinatura
$status:=$key.verify($message;$signature;New object("hash";"SHA256"))
ASSERT($status.success)
Resumo
4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey cria um novo objeto |
.curve : Text curva normalizada nome da chave |
.decrypt( message : Text ; options : Object ) : Object descifra o parâmetro message utilizando a chave private |
.encrypt( message : Text ; options : Object ) : Text encrypts the message parâmetro usando a chave public |
.getPrivateKey() : Text devolve a chave privada do objeto |
.getPublicKey( ) : Text devolve a chave pública do objeto |
.sign (message : Text ; options : Text) : Text assina a representação utf8 de uma string message |
.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 message |
4D.CryptoKey.new()
Histórico
Versão | Mudanças |
---|---|
v18 R4 | Adicionado |
4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey
Parâmetros | Tipo | 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 |
|
A função 4D.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 | Tipo | Descrição |
---|---|---|
curve | texto | Nome da curva ECDSA |
pem | text | Definição PEM de uma chave de cifrado a carregar |
size | integer | Tamanho da chave RSA em bits |
tipo | text | Tipo da chave: "RSA", "ECDSA" ou "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
Parâmetros | Tipo | Descrição | |
---|---|---|---|
message | Texto | -> | String de mensagens a decodificar utilizando options.encodingEncrypted e descifrar. |
options | Objeto | -> | Opções de decodificação |
Resultados | Objeto | <- | Estado |
A função .decrypt()
descifra o parâmetro message utilizando a chave private. O algoritmo utilizado depende do tipo da chave.
A chave deveser do estilo RSA, o algoritmo é RSA-OAEP (ver RFC 3447).
options
Propriedade | Tipo | Descrição |
---|---|---|
hash | texto | Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512". |
encodingEncrypted | texto | 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
A função devolve um objeto "status" com a propriedade success
definida como true
se message puder ser descifrada com êxito.
Propriedade | Tipo | Descrição |
---|---|---|
success | booleano | True se a mensagem tiver sido decifrada com êxito |
result | texto | Mensagem decifrado e decodificado utilizando options.encodingDecrypted |
errors | collection | Se success for false , pode conter uma coleção de erros |
Caso message não possa ser decifrado por não ter sido criptografado com a mesma chave ou algoritmo, o objeto status
que se devolve conter uma coleção de erros em status.errors
.
.encrypt()
Histórico
Versão | Mudanças |
---|---|
v18 R4 | Adicionado |
.encrypt( message : Text ; options : Object ) : Text
Parâmetros | Tipo | Descrição | |
---|---|---|---|
message | Texto | -> | String de mensagens a codificar utilizando options.encodingDecrypted e encriptar |
options | Objeto | -> | Opções de codificação |
Resultados | 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.
A chave deve ser do estilo RSA, o algoritmo é RSA-OAEP (ver RFC 3447).
options
Propriedade | Tipo | Descrição |
---|---|---|
hash | texto | Algoritmo Digest a utilizar. Por exemplo: "SHA256", "SHA384", ou "SHA512". |
encodingEncrypted | texto | Codificação utilizada para converter a mensagem binária criptografada na string resultante. Pode ser "Base64", ou "Base64URL". Por padrão é "Base64". |
encodingDecrypted | texto | Codificação utilizada para converter o parâmetro mensagem na representação binaria a encriptar Pode ser "UTF-8", "Base64" ou "Base64URL". Por padrão é "UTF-8". |
Resultados
O valor devolvido é uma mensagem criptografada.
.getPrivateKey()
Histórico
Versão | Mudanças |
---|---|
v18 R4 | Adicionado |
.getPrivateKey() : Text
Parâmetros | Tipo | Descrição | |
---|---|---|---|
Resultados | 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.
Resultados
O valor devolvido é a chave privada.
.getPublicKey()
Histórico
Versão | Mudanças |
---|---|
v18 R4 | Adicionado |
.getPublicKey( ) : Text
Parâmetros | Tipo | Descrição | |
---|---|---|---|
Resultados | 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.
Resultados
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
Parâmetros | Tipo | 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 .sign()
assina a representação utf8 de uma string message utilizando as chaves de objeto CryptoKey
e as options fornecidas. Devolve sua assinatura em formato base64 ou base64URL, dependendo do valor do atributo options.encoding
que tiver passado.
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 | 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 | Representação que se utilizará para a assinatura de resultados. Valores possíveis: "Base64" ou "Base64URL". Por padrão é "Base64". |
Resultados
Representação utf8 da string message.
.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
Parâmetros | Tipo | 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 |
Resultados | Objeto | <- | Estado da verificação |
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 publica.
options
Propriedade | Type | 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 | 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 | text | Representação de uma assinatura fornecida. Valores possíveis: "Base64" ou "Base64URL". Por padrão é "Base64". |
Resultados
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).
Caso a assinatura não possa ser confirmada porque message não foi assinada com a mesma chave ou algoritmo, o objeto status
retornado terá um erro de coleção em status.errors
.
Propriedade | Tipo | Descrição |
---|---|---|
success | booleano | True se a assinatura corresponder com a mensagem |
errors | collection | Se success for false , pode conter uma coleção de erros |