How Croc Derives the Room Name from a Code Phrase

Croc derives the room name by SHA-256 hashing the first four characters of the shared secret combined with a random suffix, creating a deterministic internal identifier that prevents accidental cross-talk between transfers.

When using schollz/croc to transfer files securely, the human-readable code phrase (also called the shared secret) must be converted into an internal room name that connects sender and receiver. Understanding exactly how the room name is derived from the code phrase reveals why the same phrase always locates the correct peer while keeping concurrent transfers isolated from one another.

How the Room Name Is Derived from the Code Phrase

The derivation process implemented in src/croc/croc.go follows a deterministic yet collision-resistant pipeline:

1. Extract the first four characters of the code phrase to form the base identifier.
2. Append a random suffix (hashExtra) generated when the transfer initializes.
3. Hash the concatenated string using SHA-256.
4. Encode the result into a short alphanumeric room identifier.

Extracting the Deterministic Prefix

Croc takes the first four characters of the user-provided code phrase as the deterministic component. This ensures that any two clients entering the same phrase will generate the identical base string, allowing the receiver to calculate the same target room as the sender without prior communication.

Adding the Random Suffix (hashExtra)

To prevent collisions when the same code phrase is used for multiple independent transfers, Croc appends a small random string called hashExtra. This suffix guarantees that concurrent transfers using identical phrases generate unique room names, eliminating the risk of accidental cross-talk or connection hijacking.

SHA-256 Hashing and Encoding

The actual hashing occurs in src/croc/croc.go at line 251:

roomNameBytes := sha256.Sum256([]byte(c.Options.SharedSecret[:4] + hashExtra))

This produces a 32-byte SHA-256 sum. Croc then encodes these bytes into a short alphanumeric string—typically hexadecimal or base-36—to serve as the final room name used in the TCP handshake.

Implementation Details in the Source Code

The room name derivation logic resides primarily in src/croc/croc.go, with supporting infrastructure handling phrase parsing and mnemonic generation:

• src/cli/cli.go: Parses the code phrase from the --code flag or CROC_SECRET environment variable and invokes resolveSendSharedSecret to process the input.
• src/croc/croc.go: Performs the SHA-256 hashing of the concatenated four-character prefix and random suffix to produce roomNameBytes.
• src/mnemonicode/mnemonicode.go: Generates the mnemonic word lists that form the human-readable code phrase displayed to users.

Practical CLI Examples

When you run Croc from the command line, the room name derivation happens automatically behind the scenes based on your code phrase.

Letting Croc generate a random code phrase:

$ croc send myfile.txt
Sending myfile.txt
Code phrase: orange-turkey-glade-42-...

# Internal room name: a7f3c2 (derived from first 4 chars + suffix)

Using a custom shared secret with the same derivation on both ends:

# Sender

$ export CROC_SECRET=pepper-mango-tide-23
$ croc send secret.txt

# Generates room name: 5b9d1e

# Receiver

$ export CROC_SECRET=pepper-mango-tide-23
$ croc receive

# Connects to room 5b9d1e derived from the same calculation

The room name itself never appears in the user interface; it functions purely as an internal networking identifier.

Summary

• Croc derives the room name by taking the first four characters of the code phrase, appending a random hashExtra suffix, and hashing the result with SHA-256.
• This process occurs in src/croc/croc.go and produces a deterministic 32-byte identifier encoded as an alphanumeric string.
• The random suffix ensures that multiple transfers using the same code phrase generate unique rooms, preventing collisions on the relay server.
• While the code phrase is visible to users, the room name remains an internal implementation detail used to map TCP connections.

Frequently Asked Questions

What is the difference between the code phrase and the room name in Croc?

The code phrase (or shared secret) is the human-readable string users exchange, such as "orange-turkey-glade-42". The room name is an internal alphanumeric hash derived from the first four characters of this phrase plus a random suffix. While the code phrase is visible and entered by users, the room name operates behind the scenes to identify the specific connection endpoint on the relay server.

Why does Croc only use the first four characters of the code phrase for the room name?

Using only the first four characters provides sufficient entropy to identify the transfer while maintaining deterministic behavior across distributed clients. This truncation ensures that both sender and receiver calculate the same base string independently when given the identical full code phrase, enabling the connection handshake to succeed without transmitting the entire phrase to the server.

Is the room name visible to users during a file transfer?

No, the room name is never displayed to users. It functions purely as an internal identifier within the networking layer used to register and lookup connections on the relay server. Users interact only with the full code phrase, while the room name appears only in server-side room maps and potential debug logs.

How does Croc prevent two transfers using the same code phrase from interfering?

Croc appends a random suffix (hashExtra) to the first four characters of the code phrase before computing the SHA-256 hash. This ensures that even if two transfers use identical code phrases, they generate different room names and occupy different entries in the server's room map. This mechanism eliminates accidental cross-talk while preserving the ability for intended peers to connect using the same phrase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}