Add Ledger key rotation tutorial by alnoki · Pull Request #367 · aptos-labs/developer-docs

alnoki · 2024-05-28T02:09:04Z

Background

@davidiw @gedigi @hariria @hardsetting @xbtmatt

Per in-person discussions re: authentication key rotation and Ledger.

This relies on the new features from the aptos-core PR aptos-labs/aptos-core#11151 which was subsequently broken into 3 smaller PRs:

Changes

Add a tutorial on rotating the authentication key for a wallet from hot private key to Ledger and back, using localnet to demonstrate new Framework code.
Change a fenced code block with lots of escape characters from bash to text to avoid syntax highlighting issues in IDE.
Update existing authentication key rotation documentation as necessary with important caveats.
Crosslink Ledger and standard key rotation documents.
Fix header hierarchy where it resulted in unintuitive navigation.

Testing

From in apps/nextra:

npx -p pnpm@8.9.0 pnpm dev

Install the aptos-core CLI from source using [Framework] Safe onchain key rotation address mapping for standard accounts aptos-core#14309 (or main, once it merges)
Follow http://localhost:3030/en/build/guides/key-rotation
Follow http://localhost:3030/en/build/cli/trying-things-on-chain/ledger#authentication-key-rotation

Checklist

Do all Lints pass?
- Have you ran pnpm spellcheck? (This is failing due to issues with content I have not modified)
- Have you ran pnpm fmt?
- Have you ran pnpm lint? (This is failing due to issues with content I have not modified)

vercel · 2024-05-28T02:09:07Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
developer-docs-nextra	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 13, 2024 7:14pm

netlify · 2024-05-28T02:09:20Z

✅ Deploy Preview for aptos-developer-docs ready!

Name	Link
🔨 Latest commit	`543aaa6`
🔍 Latest deploy log	https://app.netlify.com/sites/aptos-developer-docs/deploys/6687052621664a000836bcbe
😎 Deploy Preview	https://deploy-preview-367--aptos-developer-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

gregnazario

@movekevin can you take a look at this? Seems like encouraging people to rotate back and forth between different keys is not a good idea.

gregnazario · 2024-07-04T19:50:20Z

+
+This tutorial will walk you through both scenarios.
+
+<Callout type="warning" emoji="💀">


Let's use a red exclamation, instead of skulls.

We should also add, this is really only something that should be done if you know what you're doing or something similar.

Addressed in 543aaa6

Note that the callout additionally specifies not to do it until finishing the base ledger guide, which includes a power user warning

gregnazario · 2024-07-04T19:52:01Z

+If you are on a UNIX-like system, the following command can be used to start a
+fresh localnet as a background process:


I think this can go over people's heads sometimes.

Let's say macOS or Linux (I know there's BSD and other things, but it should be good enough).

I also, generally try not to suggest people to launch background processes unless they know what they're doing. Pretty easy to do things wrong there, especially since the local testnet will print output from 0x1::debug::print

Addressed in 543aaa6 with MacOS/Linux distinction and power user callout

gregnazario · 2024-07-04T19:54:32Z

+Create a private key corresponding to an authentication key, and thus initial
+account address, that starts with the vanity prefix `0xaaa`:
+
+```sh filename="Terminal"
+aptos key generate \
+    --assume-yes \
+    --output-file private-key-a \
+    --vanity-prefix 0xaaa
+```


Vanity prefixes are nice, but let's keep it to a randomly generated one, so people aren't waiting for a while to churn through prefixes to get to the rest of the tutorial.

It can actually be kinda hard to follow along if luck of the draw two accounts start with similar hex chars

Vanity address with only 3 chars is negligible time to generate, and the labelling make the tutorial flow way easier

gregnazario · 2024-07-04T19:56:42Z

+<Callout type="info" emoji="🧠">
+As a best practice, this command uses a [BIP44 account index] offset of 1000 to
+indicate that the account is secured by a rotated authentication key on a
+Ledger.
+
+This practice aids in profile recovery, as shown below.
+</Callout>


I'm not sure what that means.

Maybe it's better to say that it's best practice to choose a common large number, such as 1000 to ensure it doesn't conflict with already existing ledger accounts.

Addressed in 543aaa6

gregnazario · 2024-07-04T19:58:55Z

+```sh filename="Terminal"
+aptos account rotate-key \
+    --assume-yes \
+    --new-derivation-index 1000 \


I don't think this is in the CLI yet?

At least not 3.4.1

As I mentioned in the PR description

Install the CLI from source, as described in aptos-labs/aptos-core#11151

This PR pairs simply because I had to split docs and source into two separate repos aptos-labs/aptos-core#11151

Noting that I've updated the PR description per the recent set of aptos-core PRs that have merged, to stipulate installing the latest Framework updates

gregnazario · 2024-07-04T19:59:58Z

+<Callout type="info" emoji="🧠">
+If you are using a UNIX-like machine:
+
+```shell filename="Terminal"
+rm private-key-*
+```
+</Callout>


This is really dangerous, please remove it.

Someone who copies and pastes this could wipe out other private keys. Ideally should not be having a rm ...* command

Addressed in 543aaa6

gregnazario · 2024-07-04T20:02:26Z

+If you are using a UNIX-like machine:
+
+```shell filename="Terminal"
+aptos config delete-profile --profile ledger-wallet-1000


This is also not a command?

As I mentioned in the PR description

Install the CLI from source, as described in aptos-labs/aptos-core#11151

This PR pairs simply because I had to split docs and source into two separate repos aptos-labs/aptos-core#11151

Noting that I've updated the PR description per the recent set of aptos-core PRs that have merged, to stipulate installing the latest Framework updates

alnoki · 2024-07-04T20:30:59Z

@gregnazario thanks for the above comments. I believe I've addressed all where applicable

Just flagging here again that this PR requires aptos-labs/aptos-core#11151, without which there is no support for ledger auth key rotation

I'd try and do everything in one PR (docs and CLI source updates), but alas there is no longer a monorepo

Seems like encouraging people to rotate back and forth between different keys is not a good idea.

Before ledger support became available, plenty of projects launched under hot keys (and many still do, unfortunately, due to the >20kb issue on ledger), and without the CLI updates proposed in the linked PR, there is no way to secure an upgradeable package with anything other than a hot key

I agree that key rotation is advanced and should be reserved for specific use cases, but securing Move packages with accounts that don't use hot keys is important for ecosystem OpSec

hariria · 2024-08-16T22:50:54Z

+not rotate an account's authentication key to a key that is already in the
+table, as this attack that would prevent lookup of the valid originating address
+that the holder of an authentication key had previously approved.


Suggested change

not rotate an account's authentication key to a key that is already in the

table, as this attack that would prevent lookup of the valid originating address

that the holder of an authentication key had previously approved.

not rotate an account's authentication key to a key that is already in the

table, as this attack would prevent lookup of the valid originating address

that the holder of an authentication key had previously approved.

Addressed in 806a984

hariria · 2024-08-16T22:51:38Z

+mapped to in the table (since the table is only updated upon during rotation,
+not upon standard account generation).


Suggested change

mapped to in the table (since the table is only updated upon during rotation,

not upon standard account generation).

mapped to in the table (since the table is only updated during rotation,

not upon standard account generation).

Addressed in 806a984

hariria · 2024-08-16T22:52:30Z

+
+<Callout type="info" emoji="🧠">
+The [`account::rotate_authentication_key_call`] was introduced to support
+non-standard key algorith, like passkeys, which cannot produce proofs of


Suggested change

non-standard key algorith, like passkeys, which cannot produce proofs of

non-standard key algorithms, like passkeys, which cannot produce proofs of

Addressed in 806a984

hariria · 2024-08-16T22:53:13Z

+if so, verifies that the rotating account's address is the one mapped to in the
+table.
+
+This means that if an arbitary account's authentication key is rotated to


Suggested change

This means that if an arbitary account's authentication key is rotated to

This means that if an arbitrary account's authentication key is rotated to

Addressed in 806a984

hariria

Some nits and otherwise it looks good to me. Will let @gregnazario take a final pass

hariria · 2024-08-16T22:56:55Z

+
+<Callout type="warning" emoji="❗">
+Before you start this tutorial make sure you have completed the
+[key rotation guide](../../advanced-guides/key-rotation.mdx).


All of the relative links to the key rotation guide do not work for me when testing it in the preview.

It looks like advanced-guides was renamed to guides

Resolved in c32f593

alnoki · 2024-08-18T04:07:22Z

@hariria I believe I've addressed all your recent comments and that I had previously addressed all comments from @gregnazario

I've updated the PR description for more clarity on the associated aptos-core PRs

igor-p · 2024-09-13T19:23:41Z

Discussed with @gregnazario, ok to merge.

alnoki added 4 commits May 23, 2024 17:35

Being adding ledger auth key rotation tutorial

45cc217

Add more wallet setup steps

7c11db8

Add final tutorial steps

06298bc

Add final proofreading

974adb1

alnoki requested review from 0xZihan and gregnazario as code owners May 28, 2024 02:09

vercel Bot deployed to Preview May 28, 2024 02:13 View deployment

gedigi reviewed May 30, 2024

View reviewed changes

Comment thread apps/nextra/pages/en/build/cli/trying-things-on-chain/ledger.mdx Outdated

gregnazario reviewed Jun 1, 2024

View reviewed changes

alnoki mentioned this pull request Jun 1, 2024

[CLI][Ledger] Incorporate key rotation support for Ledger aptos-labs/aptos-core#13515

Closed

5 tasks

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into ledger-key-rotation

66f1d23

vercel Bot deployed to Preview June 5, 2024 21:32 View deployment

alnoki mentioned this pull request Jun 6, 2024

[CLI][Framework][Ledger] Add Ledger key rotation and more profile management to CLI, fix/extend associated Framework code aptos-labs/aptos-core#11151

Closed

Update base key rotation docs

3b954dc

vercel Bot deployed to Preview June 6, 2024 06:16 View deployment

alnoki marked this pull request as draft June 6, 2024 06:16

Clarify invalid rotations

d08ea78

vercel Bot deployed to Preview June 6, 2024 06:31 View deployment

Add proven vs unproven key rotation summary

4b7419b

vercel Bot deployed to Preview June 7, 2024 01:26 View deployment

Begin key rotation tutorial refactors

d96966e

vercel Bot deployed to Preview June 8, 2024 01:23 View deployment

Finalize base key rotation tutorial

e7639e8

vercel Bot deployed to Preview June 8, 2024 02:17 View deployment

Add minor typo fixes in key rotation tutorial

4a95bca

vercel Bot deployed to Preview June 8, 2024 02:25 View deployment

Add Ledger key rotation tutorial

a486bcc

alnoki requested review from gedigi and gregnazario June 10, 2024 02:54

vercel Bot deployed to Preview June 10, 2024 02:57 View deployment

Merge branch 'main' into ledger-key-rotation

8459190

gregnazario requested a review from hariria as a code owner June 21, 2024 21:36

vercel Bot deployed to Preview June 21, 2024 21:40 View deployment

Merge branch 'main' into ledger-key-rotation

dc8b3c0

vercel Bot deployed to Preview July 4, 2024 19:02 View deployment

gregnazario reviewed Jul 4, 2024

View reviewed changes

Address PR comments

543aaa6

vercel Bot deployed to Preview July 4, 2024 20:28 View deployment

alnoki mentioned this pull request Jul 22, 2024

[CLI] Add minimal Ledger key rotation support aptos-labs/aptos-core#14084

Merged

alnoki mentioned this pull request Aug 13, 2024

[CLI] Safe config profile management aptos-labs/aptos-core#14266

Merged

hariria requested a review from gregnazario August 16, 2024 22:47

hariria reviewed Aug 16, 2024

View reviewed changes

hariria approved these changes Aug 16, 2024

View reviewed changes

hariria reviewed Aug 16, 2024

View reviewed changes

alnoki mentioned this pull request Aug 18, 2024

[Framework] Safe onchain key rotation address mapping for standard accounts aptos-labs/aptos-core#14309

Merged

alnoki added 2 commits August 17, 2024 20:47

Merge branch 'main' into ledger-key-rotation

8cf38dc

Fix typos

806a984

vercel Bot deployed to Preview August 18, 2024 03:53 View deployment

Fix relative links for renamed folder

c32f593

vercel Bot deployed to Preview August 18, 2024 04:04 View deployment

alnoki mentioned this pull request Aug 18, 2024

[AIP-101][Discussion] Safe onchain key rotation address mapping for standard accounts aptos-foundation/AIPs#487

Closed

Merge branch 'main' into ledger-key-rotation

59b3c66

vercel Bot deployed to Preview September 13, 2024 19:14 View deployment

igor-p merged commit a63a255 into aptos-labs:main Sep 13, 2024


		This tutorial will walk you through both scenarios.

		<Callout type="warning" emoji="💀">

		If you are on a UNIX-like system, the following command can be used to start a
		fresh localnet as a background process:

		mapped to in the table (since the table is only updated upon during rotation,
		not upon standard account generation).

	non-standard key algorith, like passkeys, which cannot produce proofs of
	non-standard key algorithms, like passkeys, which cannot produce proofs of

	This means that if an arbitary account's authentication key is rotated to
	This means that if an arbitrary account's authentication key is rotated to

Conversation

alnoki commented May 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Changes

Testing

Checklist

Uh oh!

vercel Bot commented May 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented May 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for aptos-developer-docs ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

gregnazario left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alnoki commented Jul 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hariria left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

alnoki commented May 28, 2024 •

edited

Loading

vercel Bot commented May 28, 2024 •

edited

Loading

netlify Bot commented May 28, 2024 •

edited

Loading

gregnazario left a comment •

edited

Loading

alnoki commented Jul 4, 2024 •

edited

Loading