From aaa545321694eb33133d3b6a63d57a6567fe3d8d Mon Sep 17 00:00:00 2001 From: Andrew Danger Lyon Date: Fri, 16 Feb 2024 21:26:53 -0800 Subject: [PATCH] fixing headers and implementing level skipping in TOCs. updates in WHY --- src/docs.md.njk | 41 +++++++++++++++++++++-------------------- src/stampnet.md.njk | 21 +++++++++++++-------- src/why.md.njk | 10 +++++----- 3 files changed, 39 insertions(+), 33 deletions(-) diff --git a/src/docs.md.njk b/src/docs.md.njk index 618ecee..77cbb1e 100644 --- a/src/docs.md.njk +++ b/src/docs.md.njk @@ -1,20 +1,21 @@ --- layout: page.njk title: 'Documentation' -generate_toc: true +generate_toc: + skip_levels: 1 --- {% from 'includes/components/transaction.njk' import main as transaction %}
{:toc}
-## Core concepts +# Core concepts Let's go over the different pieces that make up the Stamp protocol and how they fit together. First off, we'll look at identities: what it is and the pieces that make an identity in Stamp. -### Identity +## Identity Your identity in Stamp is a collection of claims you make about yourself, "stamps" (signatures) from other identities on your claims that create @@ -194,7 +195,7 @@ stamps: [] ``` -#### Fingerprints +### Fingerprints Although identifiers are unique, it's possible someone could maliciously generate one similar enough to another one that people might be fooled. For this, we have identity fingerprints: @@ -209,7 +210,7 @@ fingerprint. Both identifier strings and fingerprints, when used together, offer protection against impersonation. That said, [stamps] are the ultimate way to defend against impersonation. -### Claims +## Claims Your identity contains pieces of information about you that others can verify. These are known as "claims" and form a basic building block of your identity. This can be something @@ -262,7 +263,7 @@ for example) and if you changed hosts you could create a new claim with the name require buy-in from the folks at ActivityPub, but it's an example of how named claims can be useful as pointers in the distributed/decentralized landscape. -### Stamps +## Stamps A "stamp" is a verification by one identity that a claim on another identity has some validity. Stamps not only allow you to show trust in others but also allow flows of trust through the @@ -283,7 +284,7 @@ keys such that only the stamper can decrypt and read the value. This allows the the stamper) to view and verify the claim. Stamps added to private claims are public even if the claim's value is encrypted and private. -### Policy system +## Policy system A policy is a way of assigning one or more [capabilities] (the ability to either update an identity or act on behalf of an identity) to specific keys (known as [admin keys][admin-keys]). No capabilities are @@ -325,7 +326,7 @@ this is a group identity. > as Stamp transactions, it becomes possible to use a group Stamp identity as a conduit for democratic > participation in other systems. -#### Admin keys +### Admin keys An admin key is a *cryptographic signing key* that lives in the identity's keychain which can be granted [capabilities] (the ability to modify or act on behalf of the identity) with the use of policies. @@ -337,7 +338,7 @@ as defined by a policy, it becomes "valid" and can be verified by other identiti Admin keys have a mandatory `name` field and optional `description` field, allowing to distinguish between them more easily than having you memorize a bunch of base64 public key values. -#### Capabilities and contexts +### Capabilities and contexts Capabilities are granted to various admin keys through the policy system. A capability can grant a permission in all cases, or be restricted to *certain contexts.* For instance, a capability might grant @@ -386,7 +387,7 @@ Context | Description -#### Recovery +### Recovery We've seen the policy system allows multi-signature management of an identity. This in itself might seem fairly esoteric, but it has one advantage to the regular, down-home individual Stamp user: recovery. @@ -400,7 +401,7 @@ How you set this up is up to you: maybe you want your grandson to be able to res your sister, and one of your two parents. Maybe four of six friends and an institutional identity provider. The only limitation is your imagination, and which people you trust. -### Keychain +## Keychain The keychain is a place to hold non-[admin][admin-keys] keys. This enables some of the more basic functions of Stamp identities. For instance, you can store an asymmetric key that allows others to send you encrypted @@ -419,11 +420,11 @@ you might have a key specifically for emails named `email/default`. The keychain also stores revoked keys, allowing old messages or signatures to be read/verified while discouraging using those keys going forward. -## Architecture +# Architecture Let's go over some important pieces about how Stamp works. -### Transactions +## Transactions At the core of Stamp is the concept of transactions. A transaction is signed message that can either *modify the identity* (create a new claim, revoke a stamp, etc) or *act on the behalf of the identity* @@ -496,7 +497,7 @@ identity is stolen, it is protected by your master key (so choose a good passphr your identity, the private data is stripped out entirely, retaining only public keys and HMACs of private data. The protocol is designed with privacy from the ground up. -### DAG +## DAG We've covered [transactions], but one part of them we kind of glossed over: the `previous_transactions` field. What is this? @@ -768,11 +769,11 @@ signatures: ``` -### Algorithms +## Algorithms Let's go over some of the cryptographic algorithms Stamp uses. -#### Serialization +### Serialization Stamp's primary binary serialization format is [ASN.1 DER][asn1] (yes, that's its real name). This expressive serialization format was purpose-built for cryptographic operations and allows *reliably* @@ -786,7 +787,7 @@ instead of prepending the hash-type to the serialized base64, Stamp appends them allows for "vanity" identity IDs that don't have to start with the characters `A` or `B` etc: you can have `fred-x895-9idf8` instead of `Afred-x895-9idf8`. -#### Hashing +### Hashing Stamp uses cryptographic hashes for two purposes: to turn a [serialized][serialization] `TransactionEntry` into a `TransactionID` and to create [policy][policies] IDs from the `TransactionID` that created them. @@ -795,20 +796,20 @@ Hashes are created using a multihash format. What this means is that each hash i what kind of hash it is, allowing expansion for an arbitrary number of hashing algorithms. Currently, Stamp has only implemented [Blake3][blake3] but supports adding more down the road. -#### Signing +### Signing WIP - ed25519 -#### Cryptography +### Cryptography WIP - xchacha20poly1305 - curve25519xchacha20poly1305 -#### Private claims +### Private claims WIP diff --git a/src/stampnet.md.njk b/src/stampnet.md.njk index 3f3aab3..3373477 100644 --- a/src/stampnet.md.njk +++ b/src/stampnet.md.njk @@ -1,21 +1,26 @@ --- layout: page.njk title: 'StampNet' +generate_toc: + skip_levels: 1 --- -
-This page is a work in progress and will be created and updated as StampNet comes to life. -
- -{#
{:toc}
+# StampNet + +StampNet is a work in progress and this page will be updated over time to reflect the +progress made on it. As currently planned, there are two main components to StampNet. + ## Sync -WIP +The Sync protocol allows syncing your identity securely between devices you own. This +allows you to bring your Stamp identity with you wherever you are in a seamless fashion. ## Publish -WIP -#} +The Publish protocol allows publishing your Stamp identity to a global network that allows +others to look your identity up either by its identifier string, your name, or your email. +This will make it possible to retrieve identities quickly, creating a foundation for +secure messaging between identities and establishing trust by crawling the identity network. diff --git a/src/why.md.njk b/src/why.md.njk index 108ea77..e536375 100644 --- a/src/why.md.njk +++ b/src/why.md.njk @@ -4,11 +4,11 @@ title: 'Stamp: Why did you build this?' og_image: '/assets/images/logo-v3.svg' --- -## Why did you build this?? +# Why did you build this?? Identity is a core concept to how humans interact with each other and form relationships. It allows us to distinguish one person from another, enabling us to truly know somebody. -We accomplish this by recognition of someone's presence, their appearance, their movement. +We accomplish this by recognition of someone's presence, their appearance, their movement, etc. However, conveying this in electronic systems is difficult. We most often represent ourselves in textual form, a medium that doesn't communicate presence, appearance, movement, or many other @@ -27,8 +27,8 @@ exists as an identity system and trust network, it falls short in a few area. 1. First, PGP only allows a handful of claims: name, email, and photo. The Stamp protocol allows you to make any number of claims, from your name, to your age, to your home address, but also custom claims, such as a state-issued ID number or being a member of an -organization. Each of these claims can be individually stamped, allowing much -more granular trust. For instance, applications might only allow membership if +organization. Each of these claims can be individually stamped, allowing +granular trust. For instance, applications might only allow membership if you have a state-issued ID stamped by a government agency. Want to write a review on that oven mitt you bought on Amazon? Better make a DMV appointment! 2. PGP also falls flat in another area: the keyservers. They allow anybody to create any @@ -47,7 +47,7 @@ party. We envision a world where online discourse can be more personal. As it stands, people must rely on corporations (Facebook, Google, etc) to vet the identities -of their users, but sometimes (read: always) these companies don't have your +of their users, but sometimes (*read: always*) these companies don't have your best interests in mind. Shouldn't you decide whether the person you're talking to is Bob from down the street or a Russian troll who wants to convince you that there are people out there who will stop at nothing to get you to eat