# Pijul identities

Pijul identities are used to identify patch authors in a manner which provides greater security and control than simply mapping authors to a name and email address. The inclusion of a name and email address can be spoofed in a way that a key signature cannot. In addition, Pijul plans to take advantage of the fact that a user's name and e-mail address are no longer tied to their submitted patches, allowing users to later change the name and e-mail address that other users see when they look at previously submitted patches.

The keys Pijul uses to identify path authors are independent of any SSH keys a user may have to interact with a remote. SSH keys are purely for authorizing the transport of patches to/from the Nest, and are not part of Pijul as a version control system.

You will need at least 1 identity to record changes, but can have as many as you like, for example `personal`, `school`, and `work`. When Pijul needs to use your identity, it will ask you to choose between them.

## Generating identities

Users can generate a new identity using `pijul identity new`. The name used for this identity is not required to bear any relationship to a Nest username or SSH identity. On success, the location of the generated identity will be displayed to the user (it should be in the same directory as your [global configuration](configuration.md)).

The program will guide you through the following questions:
| Field         | Description                                                           | Optional? | Default                              |
| ------------- | --------------------------------------------------------------------- | --------- | ------------------------------------ |
| Identity name | A unique name for your identity                                       | No        | `default`                            |
| Display name  | How Pijul refers to you (e.g. in `pijul log`)                         | No        | OS account name (e.g. "Ferris Crab") |
| Email         | An email address for people to contact                                | Yes       | No (empty)                           |
| Encryption    | If Pijul should encrypt this identity with a password                 | Yes       | No                                   |
| Expiry        | If this identity should expire by a certain date                      | Yes       | No                                   |
| Remote        | If this identity should be linked to a remote account (e.g. the Nest) | Yes       | Yes                                  |

## Proving identities

`pijul identity prove [options] <remote>` is used to associate a local identity with a remote (e.g. Nest) account. Patches submitted before proving your identity will show only the key as the author, for example `44hhwRgXtFEeAt6m3KooFCQ5VowqLoQ8YkBP93UZqm9R`. By default, `pijul id new` will do this for all new identities, so this step isn't necessary most of the time.

Example (by default, this is already done for you):
```
pijul identity prove <your_username>@ssh.pijul.com
```