Bind a Mono HttpListener Certificate with httpcfg

You will register a certificate and private key for a Mono HttpListener, check the stored entries, and remove the binding again when it is no longer needed. The examples use httpcfg from mono-devel version 6.8.0.105+dfsg-3.6ubuntu2, installed on this machine.

Allow about fifteen minutes if the certificate and key are already prepared. You need a shell, a certificate file, a private key in the format accepted by Mono, and the port used by the HTTPS listener. This guide changes the Mono certificate store but does not start, stop or reconfigure your service.

1. Check the installed command

Start with read-only checks. They do not need elevated privileges:

$ command -v httpcfg
/usr/bin/httpcfg
$ dpkg-query -W -f='${Package} ${Version}\n' mono-devel
mono-devel 6.8.0.105+dfsg-3.6ubuntu2
$ httpcfg --help
error: Unknown argument: --help
Usage is:
	httpcfg -add -port NN [-cert CERT -pvk PVK] [-p12 P12 -pwd PASSWORD]
	httpcfg -del -port NN
	httpcfg -list

This program uses single-dash options. The installed binary documents both a certificate plus private-key form (-cert and -pvk) and a password-protected PKCS#12 form (-p12 and -pwd). The local httpcfg(1) page describes the first form and does not mention the two PKCS#12 options, so rely on the installed usage when working with this package version.

2. Confirm the current store

List existing registrations before changing anything:

$ httpcfg -list

No output is a valid result when this user has no known certificates. If entries are printed, record the port numbers and decide whether the new registration is replacing one of them. Mono stores the certificates under ~/.mono/httplistener according to the local manual page. That makes the invoking account part of the configuration.

Checkpoint: identify the account that will run the listener:

$ id -un
service-user

Run httpcfg as that account. Do not add sudo just because the listener uses a low or shared port. Running the command as root writes root's per-user store, which may be invisible to a service running as another account.

3. Add a certificate and private key

For the format described by the manpage, provide the certificate, private key and port in one command. Replace every placeholder with an existing path and the listener's actual port:

$ httpcfg -add -port 8443 \
    -cert /path/to/server.cer \
    -pvk /path/to/server.pvk

The command may be run unprivileged when the input files are readable and the target account can write its Mono configuration directory. A successful run normally returns to the prompt without a success message. Check the status immediately:

$ printf 'httpcfg exit status: %s\n' "$?"
httpcfg exit status: 0
$ httpcfg -list

Confirm that the port appears in the listing. Output formatting and certificate details are version-specific, so use the port as the stable check rather than copying an imagined listing into a script.

If your input is a password-protected PKCS#12 file and the installed usage supports it, use the alternative form:

$ httpcfg -add -port 8443 \
    -p12 /path/to/server.p12 \
    -pwd 'REPLACE_WITH_THE_CERTIFICATE_PASSWORD'

A password on a command line can be visible to other local users through process inspection or shell history. Prefer a maintenance shell with restricted access, avoid leaving the command in shared history, and do not paste a real password into tickets or logs. The -pwd option is shown because this installed binary advertises it; the local manpage does not document its exact password-handling details.

4. Verify the application context

Registration is not the same as a working HTTPS endpoint. The listener must use the same port and the same account that owns the Mono store. Check the relevant process account and endpoint with your normal service tools, then make a local HTTPS request if the application is running:

$ ps -o user,pid,cmd -C mono
$ ss -ltn '( sport = :8443 )'
$ curl -kI https://127.0.0.1:8443/

The exact response depends on the application. A connection refused result usually means that nothing is listening; a TLS or certificate error points towards the certificate, private key, hostname or trust chain. The -k flag makes curl skip trust verification for a local smoke test. Do not use it as the trust model for real clients.

If the service runs as a dedicated account, inspect the store as that account rather than as your login user. If the service runs under a supervisor, check its configured user and restart policy separately. httpcfg does not restart the listener for you.

5. Remove a registration safely

Deletion is destructive to the current Mono binding. Before running it, save the original certificate and key or keep the source PKCS#12 file so that you can re-add the entry:

$ httpcfg -del -port 8443
$ printf 'httpcfg exit status: %s\n' "$?"
httpcfg exit status: 0
$ httpcfg -list

The command accepts -delete as an alias for -del. Removing the entry does not repair a running process that has already loaded its certificate, and it does not stop the service. A later listener start or reload may fail until you add the certificate again:

$ httpcfg -add -port 8443 \
    -cert /path/to/server.cer \
    -pvk /path/to/server.pvk

Re-run httpcfg -list after either operation. If a command reports a missing or bogus port, check that the value is numeric and that the option is spelled with one dash. If HTTPS still fails, verify the account, the port, file readability and the certificate/key pair before changing service permissions.

Common traps

• A certificate installed for one Unix user is not automatically available to another. Match the account used by HttpListener.
• The port is part of the registration. Adding the certificate for 8443 does not configure a listener using 443.
• The local manual page is older than the installed binary's usage output. Treat -p12 and -pwd as version-specific to this installation.
• A zero exit status confirms that httpcfg completed; it does not prove that the application is listening or that clients trust the certificate.
• Keep private keys and PKCS#12 passwords out of shared command history, process listings and support logs.