NationalSecurityAgency/ghidra · error · IOException

PKI authentication requested, but certificate authority file

Error message

PKI authentication requested, but certificate authority file not provided

What it means

Thrown by checkCertAuthorityFile() when BSim's PKI (certificate) authentication mode was selected but no certificate authority file was supplied. BSim requires the server's CA root to validate client certificates, so PKI cannot be configured without it. It is an IOException raised during data-directory initialization, start, changeauth, or add/drop-user flows whenever hostAuthentication == AUTHENTICATION_PKI.

Source

Thrown at Ghidra/Features/BSim/src/main/java/ghidra/features/bsim/query/BSimControlLaunchable.java:845

		if (hostMethod == null || hostMethod.equals(TRUST_METHOD)) {
			hostAuthentication = AUTHENTICATION_NONE;
		}
		else if (hostMethod.equals(PASSWORD_METHOD)) {
			hostAuthentication = AUTHENTICATION_PASSWORD;
		}
		else if (hostMethod.equals(CERTIFICATE_METHOD)) {
			hostAuthentication = AUTHENTICATION_PKI;
		}
	}

	/**
	 * Make sure certificate authority needed for pki was provided by user, otherwise throw exception
	 * @throws IOException if the cert file is invalid
	 * @throws GeneralSecurityException if the cert file is not a valid certificate
	 */
	private void checkCertAuthorityFile() throws IOException, GeneralSecurityException {
		if (certAuthorityFile == null) {
			throw new IOException(
				"PKI authentication requested, but certificate authority file not provided");
		}
		if (!certAuthorityFile.isFile()) {
			throw new IOException(
				certAuthorityFile.getAbsolutePath() + " is not a valid certification authority");
		}
		if (!verifyPEMFormat(certAuthorityFile)) {
			throw new GeneralSecurityException(
				"File " + certAuthorityFile.getName() + " does not appear to be a certificate");
		}
	}

	/**
	 * Locate the PostgreSQL configuration and authentication files (postgresql.conf and pg_hba.conf)
	 * and recover the settings pertinent to BSimControl.  If the data directory has not been initialized yet,
	 * run PostgreSQL's init command to perform the initialization and then tailor the configuration
	 * based on BSimControl's command-line options and the Ghidra specific configuration options
	 * @throws IOException if the module data file cannot be retrieved

View on GitHub (pinned to d5f144c24d)

Solutions

Add `--cafile /path/to/ca/root.crt` to the bsim_ctl command line.
Verify the file exists and is readable: `test -f root.crt`.
If you did not intend PKI, use `--auth scram-sha-256` (password) or `--auth trust` instead.
For adduser/dropuser against an already-PKI-configured server, ensure the CA file is still present and pass --cafile again.

Example fix

// before
bsim_ctl start --auth cert --port 8080
// after
bsim_ctl start --auth cert --cafile /etc/bsim/root.crt --dn "CN=admin" --cert /etc/bsim/client.crt --port 8080

Defensive patterns

Strategy: validation

Validate before calling

// Before calling BSimControlLaunchable / building the command, validate PKI inputs.
boolean pkiRequested = "cert".equals(authMode);
if (pkiRequested && (caFilePath == null || caFilePath.isBlank())) {
    throw new IllegalArgumentException(
        "--cafile <path> is required when --auth cert is used");
}

Type guard

// Narrow a parsed options object before invoking BSim control.
public boolean isPkiConfigComplete(BsimCtlOptions o) {
    if (!"cert".equals(o.auth)) return true;          // not PKI -> nothing to check
    return o.cafile != null && new File(o.cafile).isFile()
        && o.dn != null && o.dn.contains("CN=")
        && o.cert != null;
}

Try / catch

try {
    bsimControl.start(args);
} catch (IOException e) {
    if (e.getMessage() != null && e.getMessage().contains("certificate authority file not provided")) {
        // surface a user-facing hint to add --cafile
        throw new UserFacingException("PKI auth requires --cafile <CA path>", e);
    }
    throw e;
}

Prevention

Treat --auth cert, --cafile, --dn, and --cert as a single required group in any wrapper script.
Validate the option group before invoking bsim_ctl and fail fast with a clear message.
Keep a checked-in example command per auth mode.

When it happens

Trigger: Running `bsim_ctl start` (or adduser/dropuser/changeauth) with `--auth cert` but omitting `--cafile <path>`. The option parser sets hostAuthentication/localAuthentication to AUTHENTICATION_PKI on `--auth cert` and leaves certAuthorityFile null; checkCertAuthorityFile() then throws.

Common situations: Operator forgets the --cafile flag after switching to certificate auth; copy-pasting a start command from a password-auth setup into a PKI deployment; misreading --cert (client cert) for --cafile (server CA).

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/13b4ff2ed8bbcbaa. Report an issue: GitHub.