docs/docs/security/keys.md

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 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:

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:

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.