Keyring

By Adam Robichaud.

A BepInEx mod for Valheim that remembers server passwords so you stop retyping them. The first time a server accepts your password, Keyring saves it. The next time you join that server, the password dialog never appears: Keyring answers it for you.

• Client-side only. Nothing needs to be installed on the server.
• Passwords are stored in the Windows Credential Manager, encrypted by Windows (DPAPI) under your user account. They are never written to the mod's config file, the game's log, or any file in the game folder.
• A password is only saved after the server has accepted it, so a typo is never stored.
• If a saved password stops working (the server changed it), Keyring forgets it and shows the dialog again.
• Manage saved entries from the console (F5) with keyring list, keyring forget <n>, keyring forget all and keyring status, or in Windows itself under Control Panel → Credential Manager → Windows Credentials, where they appear as Valheim/Keyring/....
• A Continue entry at the top of the main menu takes you straight back into the last world or server you played on, with the character you used. Hover it (or select it with the keyboard or a gamepad) to see what it would join: the server name, how it is reached (dedicated address, Steam host or crossplay host) and the character. It is greyed out until you have joined something once, and clears itself if the world or character has since been deleted. Together with the saved password, that is one click from menu to game.

Where the password goes, and why

Valheim servers check the password on every connection, and the hash they expect uses a salt that changes whenever the server restarts. So a mod that logs you in must keep the actual password, not a hash. The question is only where.

Keyring uses the operating system's credential store rather than its own file:

Option	Readable by	Notes
Plain text in a config file	anyone who can read the file, any backup, any cloud sync	What most "remember password" hacks do. Not used.
A file encrypted with a key kept next to it	same as above, the key is right there	Obfuscation, not protection. Not used.
Windows Credential Manager (DPAPI)	only processes running as your Windows user on this PC	Encrypted with a key derived from your Windows login. Copying the files to another machine or user yields nothing. Used.

What this does not protect against: malware already running under your own Windows account can read anything you can, including these entries. That limit applies to every password manager and browser on the machine too. Keyring keeps the password out of files that get copied, shared, synced or pasted into bug reports.

Other platforms

• Linux (native client) and macOS: there is no backend yet, so nothing is saved and the password dialog works as usual. A libsecret / Keychain backend would slot in behind the same ICredentialStore interface.
• Wine / Proton: Wine emulates the Windows credential API but stores entries with weak obfuscation, so Keyring refuses to save there unless you set AllowWineStore = true.

Building

Requirements: .NET SDK 6 or newer, Valheim installed, BepInEx 5.4.x installed (plain or via a mod manager).

1. Copy Paths.props to Paths.local.props and point the three properties at your install:

   • ValheimManaged: .../Valheim/valheim_Data/Managed
   • BepInExCore: the folder holding BepInEx.dll and 0Harmony.dll
   • PluginsDir: the BepInEx/plugins folder to deploy into (leave empty to skip deployment)

2. Build:

   dotnet build -c Release
   

The DLL lands in bin/Release/Keyring.dll and is copied to <PluginsDir>/PuhPuhBurr-Keyring/ (or into an existing install of the mod, wherever the mod manager put it). A Release build also writes thunderstore/PuhPuhBurr-Keyring-<version>.zip, which Thunderstore Mod Manager / r2modman can import via Settings → Profile → Import local mod.

Configuration

BepInEx/config/com.puhpuhburr.keyring.cfg is created on first run.

Key	Default	Meaning
RememberPasswords	true	Save a password once a server accepts it.
AutoLogin	true	Answer the password dialog with the saved password. Off: still saves, but you type it.
ForgetRejected	true	Delete a saved password the server rejects.
ShowMessages	true	Show a short top-left message after spawning when a password was saved or used.
AllowWineStore	false	Allow saving under Wine/Proton despite its weak store.
ShowContinueButton	true	Add the Continue entry to the main menu.

The section 9 - Last session holds what Continue will rejoin (kind, world or server address, server name, character). The mod writes it; set LastKind = None to forget it. No password is ever stored there.

The -password <pw> command line option still works and takes precedence; passwords given that way are not saved.

How it works

Valheim's join handshake, on the client, is ZNet.RPC_ClientHandshake (server says whether a password is needed), ZNet.OnPasswordEntered (the dialog submits), ZNet.RPC_PeerInfo (connection accepted) and ZNet.RPC_Error (rejected, including ErrorPassword). Keyring adds Harmony patches to those four:

1. After the handshake, if a password is needed and one is saved for ZNet.GetServerString() (the game's own identity for the server you picked: Steam ID, address and port, or PlayFab ID), it calls OnPasswordEntered with it.
2. When you type a password, it is held in memory as pending.
3. When RPC_PeerInfo reports the connection as established, the pending password is written to the credential store with the server's name as the comment.
4. On ErrorPassword, the pending password is dropped and, if the saved one was what got rejected, it is deleted.

Continue hooks the menu in FejdStartup. When the menu hands over to the game (TransitionToMainScene) the world or server and the selected character are captured; once the player has spawned they are committed to the config, so a failed connection never becomes what Continue retries. The button itself is a clone of the Start Game button inserted above it. Clicking it selects the remembered character and then either queues the server and calls OnCharacterStart (the same path the game uses for invites) or opens the world list, picks the world by name and calls OnWorldStart.

Credential Manager access is a few advapi32 calls (CredWriteW, CredReadW, CredDeleteW, CredEnumerateW) in WindowsCredentialStore.cs. Entries are generic credentials named Valheim/Keyring/<server identity> with persistence LOCAL_MACHINE (survives logoff, still per-user). Managed and unmanaged copies of the secret are zeroed once they have been handed to Windows.