How to Use the `--curve` Flag to Select Different Encryption Curves in croc

The --curve flag lets you specify which elliptic curve the PAKE (Password-Authenticated Key Exchange) protocol uses for key derivation, supporting p256 (default), p384, p521, and x25519 to balance security strength and computational performance.

The schollz/croc file transfer tool relies on PAKE to establish encrypted connections without pre-shared keys. By using the --curve flag to select different encryption curves, you can tune the cryptographic handshake for specific hardware constraints or security requirements.

How the --curve Flag Works

CLI Flag Definition

In src/cli/cli.go, the flag is registered using pake.AvailableCurves() to dynamically expose supported curves:

&cli.StringFlag{
    Name:  "curve",
    Value: "p256",
    Usage: "choose an encryption curve (" + strings.Join(pake.AvailableCurves(), ", ") + ")",
},

This definition sets p256 as the default and pulls the valid options from the underlying pake library.

PAKE Initialization and Handshake

When initiating a transfer, the sender reads c.Options.Curve and transmits the curve name as the second byte slice (Bytes2) in the PAKE handshake. The receiver extracts this value from the incoming message and initializes the PAKE instance accordingly. In src/croc/croc.go (lines 2104-2107), the initialization occurs:

log.Debugf("using curve %s", string(m.Bytes2))
c.Pake, err = pake.InitCurve([]byte(c.Options.SharedSecret[5:]), 1, string(m.Bytes2))

If the curve transmitted by the sender is not supported by the receiver’s pake library version, InitCurve returns an error and the connection aborts immediately.

Available Encryption Curves

The pake.AvailableCurves() function returns the following elliptic curve options:

• p256 – NIST P-256 (default; provides 128-bit security with fast execution on most hardware)
• p384 – NIST P-384 (provides 192-bit security at moderate computational cost)
• p521 – NIST P-521 (provides 256-bit security; highest strength but noticeably slower key exchange)
• x25519 – Curve25519 (provides 128-bit security with highly efficient arithmetic, optimal for mobile and embedded devices)

Practical Usage Examples

To send a file using a specific curve:

# Use Curve25519 for faster handshake on mobile devices

croc send --curve x25519 document.pdf

# Use maximum security with P-521

croc send --curve p521 sensitive-data.zip

The receiver extracts the curve automatically from the handshake, but you may explicitly specify it for documentation purposes:

croc receive --curve x25519

Summary

• The --curve flag is defined in src/cli/cli.go using pake.AvailableCurves() and defaults to p256
• In src/croc/croc.go, the pake.InitCurve() function initializes the cryptographic context using the curve transmitted in m.Bytes2
• Supported curves are p256, p384, p521, and x25519, each offering distinct security levels and performance characteristics
• The curve name is transmitted during the PAKE handshake and must match between sender and receiver for successful key derivation

Frequently Asked Questions

What happens if the sender and receiver use different curves?

The PAKE handshake will fail immediately because the receiver calls pake.InitCurve() with the curve name sent by the sender (m.Bytes2). If this curve is unsupported by the receiver’s library version or mismatched due to manual override, the function returns an error and the connection terminates before any file data transfers.

Which curve provides the best performance for mobile devices?

x25519 (Curve25519) is optimized for constrained hardware and provides the fastest key exchange while maintaining 128-bit security. Unlike NIST curves, it uses constant-time arithmetic operations that avoid side-channel leaks and execute efficiently on ARM processors commonly found in mobile devices.

How can I list available curves for my croc installation?

Run croc --help and examine the --curve flag description, which dynamically generates the list from pake.AvailableCurves(). The specific curves available depend on the version of the github.com/schollz/pake module compiled into your binary.

Does the curve choice affect file transfer speed?

No, the curve selection only impacts the initial PAKE handshake performed by pake.InitCurve(). Once the symmetric encryption key is established, the actual file transfer speed depends on your network bandwidth and the symmetric encryption algorithm, not the elliptic curve used during the initial key exchange.

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