Skip to main content

crypto.verify(mode, message, signature, publicKey, callback)

Verify message data using its public key

Availability

Agent

Parameters

Name Type Description
mode Constant The hashing type
message String or blob The data to be verified, up to 64KB in size
signature String or blob A previously generated RSA signature
publicKey String or blob The public partner of the private key used to sign the data
callback Function The function into which a verification state indicator is passed

Returns

Nothing

Description

This method is used to verify the specified message. To verify the message, it is first hashed using the type specified by the value passed into the mode parameter. Currently, only one mode is supported: the SHA256 RSA signature scheme, which is specified with the mode constant crypto.RSASSA_PKCS1_SHA256.

The signature passed into the method is used with the public partner of the private key originally used to sign the message data. This yields a second hash (also known as a ‘digest’); if the two digests match, the message data is valid.

The method returns immediately; the verification process takes place asynchronously. The result is returned via the mandatory callback function’s isVerified parameter, which will be true if the signatures match, otherwise false.

Passing an invalid mode or a malformed key will result in an exception being thrown. The value of key must be an RSA public key: DER-encoded PKCS#1 or PKCS#8 between 1024 and 4096 bits in length (inclusive).

The message to be verified must not be larger than 65536 bytes (64KB).

Though crypto.sign() returns signatures as blobs, crypto.verify() also accepts signatures as strings, for your convenience. Such strings should always be the same length as the RSA modulus, with leading zero bytes as required.

Usage Rate Limits

Use of crypto.verify() will be rate-limited as follows. Each agent has 40 usage credits which will be spent according to the length of the key used to sign or verify the data on a per-call basis:

credits used = key length in bits ÷ 1024

Credits are topped up at the fixed rate of two credits per second.

If you make a call when you have no usage credits, an exception will be thrown. Other errors are passed into the callback function’s error parameter, which will be null if no error occurred.

Note We reserve the right to alter the number of credits provided to an agent, the rate of renewal and the cost per key.

Example Code

The following code shows how a simple string can be signed using a pre-existing RSA private key and then verified. This requires both the private key and its public key partner. Enter the command

openssl genrsa -out rsa.key 2048

into a terminal on your computer to generate a fresh private key. To generate a public key from the private key, enter the command

openssl rsa -pubout < rsa.key > rsa.pub

The code uses crypto.sign to sign the data — this signature and the public key are then passed into crypto.verify() to confirm that the message data is genuine. In a real-world application, you would use the method to validate data received from an external source.