CryptoKey

The CryptoKey class in QodlyScript encapsulates an asymmetric encryption key pair.

This class is available from the 4D class store.

Example

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
var key : 4D.CryptoKey
key = 4D.CryptoKey.new(newobject("type","ECDSA","curve","prime256v1"))

  // Get signature as base64
var message, signature : string
message = "hello world"
signature = key.sign(message,newobject("hash","SHA256"))

  // Verify signature
var status : object
status = key.verify(message,signature,newobject("hash","SHA256"))
assert(status.success)

Functions and properties

4D.CryptoKey.new( settings : object ) : 4D.CryptoKey    creates a new 4D.CryptoKey object encapsulating an encryption key pair
.curve : string    normalised curve name of the key
.decrypt( message : string , options : object ) : object    decrypts the message parameter using the private key
.encrypt( message : string , options : object ) : string    encrypts the message parameter using the public key
.getPrivateKey() : string    returns the private key of the CryptoKey object
.getPublicKey() : string    returns the public key of the CryptoKey object
.sign (message : string , options : string) : string    signs the utf8 representation of a message string
.size : integer    the size of the key in bits
.type : string    name of the key type - "RSA", "ECDSA", "PEM"
.verify( message : string , signature : string , options : object) : object    verifies the base64 signature against the utf8 representation of message

4D.CryptoKey.new()

4D.CryptoKey.new( settings : object ) : 4D.CryptoKey

Parameter	Type		Description
settings	object	→	Settings to generate or load a key pair
result	4D.CryptoKey	←	object encapsulating an encryption key pair

The 4D.CryptoKey.new() function creates a new 4D.CryptoKey object encapsulating an encryption key pair, based upon the settings object parameter. It allows to generate a new RSA or ECDSA key, or to load an existing key pair from a PEM definition.

settings

Property	Type	Description
type	string	Defines the type of the key to create: "RSA": generates a RSA key pair, using .size as size. "ECDSA": generates an Elliptic Curve Digital Signature Algorithm key pair, using .curve as curve. Note that ECDSA keys cannot be used for encryption but only for signature. "PEM": loads a key pair definition in PEM format, using .pem.
curve	string	Name of ECDSA curve
pem	string	PEM definition of an encryption key to load
size	integer	Size of RSA key in bits

CryptoKey

The returned CryptoKey object encapsulates an encryption key pair. It is a shared object and can therefore be used by multiple processes simultaneously.

.curve

.curve : string

Defined only for ECDSA keys: the normalised curve name of the key. Usually "prime256v1" for ES256 (default), "secp384r1" for ES384, "secp521r1" for ES512.

.decrypt()

.decrypt( message : string , options : object ) : object

Parameter	Type		Description
message	string	→	Message string to be decoded using options.encodingEncrypted and decrypted.
options	object	→	Decoding options
Result	object	←	Status

The .decrypt() function decrypts the message parameter using the private key. The algorithm used depends on the type of the key.

The key must be a RSA key, the algorithm is RSA-OAEP (see RFC 3447).

options

Property	Type	Description
hash	string	Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512".
encodingEncrypted	string	Encoding used to convert the message parameter into the binary representation to decrypt. Can be "Base64" or "Base64URL". Default is "Base64".
encodingDecrypted	string	Encoding used to convert the binary decrypted message into the result string. Can be "UTF-8", "Base64", or "Base64URL". Default is "UTF-8".

Result

The function returns a status object with success property set to true if the message could be successfully decrypted.

Property	Type	Description
success	boolean	True if the message has been successfully decrypted
result	string	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()

.encrypt( message : string , options : object ) : string

Parameter	Type		Description
message	string	→	Message string to be encoded using options.encodingDecrypted and encrypted.
options	object	→	Encoding options
Result	string	←	Message encrypted and encoded using the options.encodingEncrypted

The .encrypt() function encrypts the message parameter using the public key. The algorithm used depends on the type of the key.

The key must be a RSA key, the algorithm is RSA-OAEP (see RFC 3447).

options

Property	Type	Description
hash	string	Digest algorithm to use. For example: "SHA256", "SHA384", or "SHA512".
encodingEncrypted	string	Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Default is "Base64".
encodingDecrypted	string	Encoding used to convert the message parameter into the binary representation to encrypt. Can be "UTF-8", "Base64", or "Base64URL". Default is "UTF-8".

Result

The returned value is an encrypted message.

.getPrivateKey()

.getPrivateKey() : string

Parameter	Type		Description
Result	string	←	Private key in PEM format

The .getPrivateKey() function returns the private key of the CryptoKey object in PEM format, or an empty string if none is available.

Result

The returned value is the private key.

.getPublicKey()

.getPublicKey() : string

Parameter	Type		Description
Result	string	←	Public key in PEM format

The .getPublicKey() function returns the public key of the CryptoKey object in PEM format, or an empty string if none is available.

Result

The returned value is the public key.

---

.pem

.pem : string

PEM definition of an encryption key to load. If the key is a private key, the RSA or ECDSA public key will be deduced from it.

.sign()

.sign (message : string , options : string) : string

Parameter	Type		Description
message	string	→	Message string to sign
options	object	→	Signing options
Result	string	←	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.

The CryptoKey must contain a valid private key.

options

Property	Type	Description
hash	string	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	string	Encoding used to convert the binary encrypted message into the result string. Can be "Base64", or "Base64URL". Default is "Base64".
pss	boolean	Use Probabilistic Signature Scheme (PSS). Ignored if the key is not an RSA key. Pass true when producing a JWT for PS@ algorithm
encoding	string	Representation to be used for result signature. Possible values: "Base64" or "Base64URL". Default is "Base64".

Result

The utf8 representation of the message string.

.size

.size : integer

Defined only for RSA keys: the size of the key in bits. Typically 2048 (default).

.type

.type : string

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. Note that ECDSA keys cannot be used for encryption but only for signature.
• "PEM": a key pair definition in PEM format, using settings.pem as .pem.

.verify()

.verify( message : string , signature : string , options : object) : object

Parameter	Type		Description
message	string	→	Message string that was used to produce the signature
signature	string	→	Signature to verify, in Base64 or Base64URL representation, depending on options.encoding value
options	object	→	Signing options
Result	object	←	Status of the verification

The .verify() function verifies the base64 signature against the utf8 representation of message using the CryptoKey object keys and provided options.

The CryptoKey must contain a valid public key.

options

Property	Type	Description
hash	text	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	boolean	Use Probabilistic Signature Scheme (PSS). Ignored if the key is not an RSA key. Pass true when verifying a JWT for PS@ algorithm
encoding	text	Representation of provided signature. Possible values are "Base64" or "Base64URL". Default is "Base64".

Result

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.

Property	Type	Description
success	boolean	True if the signature matches the message
errors	collection	If success is false, may contain a collection of errors