mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-07 06:48:19 +01:00
51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
# Public Key Cryptography
|
|
|
|
Lysand employs public key cryptography for object signing, ensuring the authenticity of the object's origin.
|
|
|
|
All public keys in Lysand **MUST** be encoded using the [ed25519](https://ed25519.cr.yp.to/) algorithm. This algorithm is favored due to its speed, security, and compact key size. Legacy algorithms such as RSA are not supported and **SHOULD NOT** be implemented using extensions due to security considerations.
|
|
|
|
While it's technically possible to implement other encryption algorithms using extensions, it's generally discouraged.
|
|
|
|
In the near future, Lysand will also support quantum-resistant algorithms, once they are incorporated into popular libraries.
|
|
|
|
Here's an example of generating a public-private key pair in TypeScript using the WebCrypto API:
|
|
|
|
```ts
|
|
const keyPair = await crypto.subtle.generateKey(
|
|
"Ed25519",
|
|
true,
|
|
["sign", "verify"]
|
|
);
|
|
|
|
// Encode both to base64 (Buffer is a Node.js API, replace with btoa and atob for browser environments)
|
|
const privateKey = Buffer.from(
|
|
await crypto.subtle.exportKey("pkcs8", keys.privateKey),
|
|
).toString("base64");
|
|
|
|
const publicKey = Buffer.from(
|
|
await crypto.subtle.exportKey("spki", keyPair.publicKey),
|
|
).toString("base64");
|
|
|
|
// Store the public and private key somewhere in your user data
|
|
```
|
|
|
|
> [!WARNING]
|
|
> Support for Ed25519 in the WebCrypto API is a recent addition and may not be available in some older runtimes, such as Node.js or older browsers.
|
|
|
|
Public key data is represented as follows across the protocol:
|
|
|
|
```ts
|
|
interface ActorPublicKeyData {
|
|
public_key: string;
|
|
actor: string;
|
|
}
|
|
```
|
|
|
|
The `public_key` field is a string that contains the user's public key. It **MUST** be encoded using base64.
|
|
|
|
Base64 encoding of public and private keys is defined as follows:
|
|
- The public key **MUST** be encoded using the `spki` format.
|
|
- The private key **MUST** be encoded using the `pkcs8` format.
|
|
- Both keys **MUST** be turned from raw bytes to base64 by turning the bytes into a sequence of UTF-16 code units, then encoding them as base64 (as shown in the example above).
|
|
|
|
The `actor` field is a string that contains the user's URI. This field is mandatory. |