# Message Signing

### Overview

This service allows end users to have their messages signed by a satellite in orbit. This is achieved using the satellite's signature key along with a current timestamp to ensure the signature cannot be backdated. The Cryptosat service manages the task of coordinating the transmission of the message to the suitable ground station when the satellite is online.

### Methods

#### sign

```javascript
sigRequest = await cryptosat.sign('your message here');
```

This method sends a message to the satellite to be signed and returns a request object that allows the user to track the status of the request.

**Parameters**

* `message` (string): The message to be signed.

**Returns**

* `sigRequest` (object): An object that allows the user to track the status of the request. This object has two methods: `status` and `result`.

***

#### status

```javascript
await sigRequest.status();
```

This method allows users to check the status of their signature request.

**Parameters**

None.

**Returns**

* `status` (string): The status of the request. When the request has been signed by the satellite and received back, the status will be `READY`.

***

#### result

```javascript
result = await sigRequest.result();
```

This method returns the result of the signature request. This should be used once the `status` method returns `Ready`.

**Parameters**

None.

**Returns**

* `result` (object): The result of the request, which contains the signature and timestamp.

### Example Usage

To validate the signature returned by the satellite, you can use the `nacl` library. Here's a short snippet to demonstrate this:

```javascript
// Require the Cryptosat library
const Cryptosat = require('cryptosat');

// Create a Cryptosat instance with the service URL
const cryptosat = new Cryptosat('https://api.cryptosat.io');

// Initiate the signing request
let sigRequest = await cryptosat.sign('Hello, world!');

// Poll the status of the request until it is ready
while (true) {
  let status = await sigRequest.status();
  if (status === 'Ready') {
    break;
  }
  // wait before polling again
  await new Promise(r => setTimeout(r, 1000));
}

// Once ready, retrieve the result
let result = await sigRequest.result();

// Fetch the public signing key from the Cryptosat. 
// IMPORTANT: In production, retrieve key out of band
let publicKey = await cryptosat.getPublicSigningKey();

// Verify the signature using NaCl
let valid = nacl.sign.detached.verify(
  new TextEncoder().encode(result.message + result.timestamp),
  result.signature,
  publicKey
);

console.log(valid ? 'Valid signature' : 'Invalid signature');
```

This code initiates a signature request with the `sign` method, periodically checks the status of the request using the `status` method, and once the status is `Ready`, it retrieves the result using the `result` method. Finally, it verifies the signature using the `nacl.sign.detached.verify` method from the `nacl` library.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cryptosat.io/cryptosat/api-documentation/message-signing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.