Generate and Feed a Safe X11 Cookie with mcookie

mcookie hands you a 128-bit hexadecimal cookie for X authority in one line, and the hard part is what you do with it afterwards. This guide shows you how to generate one, check where the randomness came from, and add it to an X display with xauth without leaking it into shell history or logs. The examples use the Debian/Ubuntu util-linux 2.39.3 installation at /usr/bin/mcookie, and none of it exposes a cookie in a URL, commits one to a file, or changes a display's access control unless you run the optional xauth step.

Allow about ten minutes. You need a shell and the util-linux package; an X server and xauth are only needed for the final integration example. Ordinary generation needs no elevated privileges. A cookie is a credential: keep it out of shared terminals, shell history, screenshots and logs.

1. Confirm the installed command

Check the binary and version before relying on an example:

$ command -v mcookie
/usr/bin/mcookie
$ /usr/bin/mcookie --version
mcookie from util-linux 2.39.3

The manpage installed with the package describes util-linux 2.39.3. On a machine where another copy appears earlier in PATH, mcookie --version may report a different release, so use the absolute path while comparing results with this guide.

Checkpoint: confirm that help shows -f or --file, -m or --max-size, and -v or --verbose. If the command is missing, install the distribution's util-linux package through its normal package-management process rather than downloading a replacement binary into a system directory.

2. Generate a cookie normally

Run mcookie with no options:

$ /usr/bin/mcookie
cab79af0591ac6ee36e8b6b85ac896ae

Your value will differ. A successful result is one line of 32 hexadecimal characters, representing 128 bits. Here is the surprising bit: the program builds that value as an MD5 digest of random information. In the installed version its preferred sources, in order, are the getrandom system call, /dev/urandom, /dev/random, and finally libc pseudo-random functions. The MD5 shape is just packaging: do not treat the result as an ordinary checksum, it is being used as a compact cookie value.

Capture it only when a following command needs it, and keep the variable in the current shell:

cookie=$(/usr/bin/mcookie)
case "$cookie" in
    ''|*[!0123456789abcdef]*)
        printf '%s\n' 'mcookie did not return lowercase hexadecimal' >&2
        exit 1
        ;;
esac
printf 'cookie length: %s\n' "${#cookie}"

Checkpoint: expected output is cookie length: 32. The check catches an empty result or unexpected text before it reaches another command, and it does not print the secret itself.

3. Inspect the randomness source

Use --verbose when diagnosing entropy availability:

$ /usr/bin/mcookie --verbose
16f8ff2a47669a1f5b090d79e24aaa23
Got 128 bytes from getrandom() function

The cookie still goes to standard output; the explanation just names a source and the amount read. Exact wording and byte counts can vary with the kernel, libc and util-linux release, so treat this as a diagnostic, not a stable format for a parser. A normal run does not require sudo.

The manpage lists these sources in preference order, and it also records a bug assumption that they will not block. If a run hangs, stop waiting rather than starting more copies: check the host's entropy and device behaviour with your operating system's diagnostics instead.

4. Add extra input without pretending it is the only secret

--file adds a file as another randomness source; a hyphen reads that source from standard input instead:

$ printf '%s\n' 'operator-supplied-seed' | /usr/bin/mcookie --file - --max-size 22
2a0d19023bb25c85606be192823ed89f

The output is still a fresh digest and will not be predictable from the displayed seed alone, because the program also draws on its normal randomness sources. This option earns its keep when an application already has an extra local source worth contributing. It is not a replacement for the operating system's random source, and a public or guessable seed does not make a cookie secret.

--max-size caps how many bytes are read from the additional file. The value takes binary suffixes such as K or KiB, or decimal suffixes such as KB. Set a deliberate limit when the input is a device, pipe or large file; without one, do not assume a regular file is cheap to read.

5. Use the cookie with xauth

Warning: only do this if you intentionally want to alter the current user's X authority database, since it changes local authentication state. Check which display is selected first:

$ printf 'display: %s\n' "${DISPLAY:-unset}"
display: :0

Replace DISPLAY_VALUE below with the display you intend to authorise. Do not paste a cookie into the command line if other users can inspect process arguments. Feeding it through a shell variable keeps it out of the command text, though the value can still be visible to tools that inspect the shell:

display_value=':0'
cookie=$(/usr/bin/mcookie) || exit 1
xauth add "$display_value" . "$cookie"
unset cookie display_value

Successful xauth add normally produces no output. Verify the entry without printing its cookie value:

xauth list "$display_value" | sed 's/[[:space:]][^[:space:]]*$/ [cookie hidden]/'

Recovery: to undo this state change, remove the matching display entry with xauth remove "$display_value". Check the display name carefully first, because removing the wrong entry can interrupt clients that rely on it. No sudo is normally appropriate: use the authority database belonging to the user who will connect to the X server.

Common traps

Done means