CERTMONGER(8)

✨ NAME ✨

okay bestie, say hi to dogtag-submit 💅

this whole page is CERTMONGER(8) from the System Manager's Manual — section 8, admin-girl territory, we love that for us 👑

🦋 SYNOPSIS 🦋

dogtag-submit -E EE-URL -A AGENT-URL [-d DIR] [-n NAME] [-i FILE] [-C
DIR] [-c FILE] [-k FILE] [-p FILE] [-P PIN] [-s serial (hex)] [-D serial
(decimal)] [-S state] [-T profile] [-O param=value] [-N | -R] [-t] [-o
option=value] [-a] [-u username] [-U userdn] [-W PASSWORD] [-w FILE] [-Y
PIN] [-y FILE] [-v] [csrfile]

🌸 DESCRIPTION 🌸

so dogtag-submit is the little helper that certmonger calls when it needs to do certificate enrollment and renewal requests against Dogtag servers. it's not normally run interactively — like, it's a behind-the-scenes girly — but you can run it by hand if you're troubleshooting. no cap 🫶

the preferred move is to ask for a renewal of an already-issued certificate, using its serial number. where does that serial come from? either:

• the CERTMONGER_CERTIFICATE environment variable, which can hold a PEM-formatted certificate, or
• the -s or -D option on the command line.

if no serial number is provided, then the client will try to get a brand new certificate by submitting a signing request to the CA. new cert, who dis ✨

the signing request that's getting submitted should be in a file whose name you pass as an argument, or fed into dogtag-submit via stdin. either works, pick your vibe.

heads up bestie: certmonger does not yet support retrieving trust information from Dogtag CAs. it's giving "not yet", not "never" 🙈

💖 OPTIONS 💖

• -E EE-URL, --ee-url=EE-URL — the top-level URL for the end-entity interface the CA provides, and it's through this one that the initial enrollment request gets submitted. typically it's http://SERVER:EEPORT/ca/ee/ca.
• -A AGENT-URL, --agent-url=AGENT-URL — the top-level URL for the agent interface the CA provides, through which the request can be approved using agent credentials. typically it's https://SERVER:AGENTPORT/ca/agent/ca.
• -i FILE, --cafile=FILE — where the file lives that holds a copy of the CA's certificate. the CA server's certificate gets verified against it. 🔍
• -C DIR, --capath=DIR — where the directory lives that holds a copy of the CA's certificate(s). again, the CA server's certificate gets verified against it.
• -D SERIAL, --serial=SERIAL — the serial number of an already-issued certificate that the client should try to get a new certificate for, in decimal form, if one can't be read from the CERTMONGER_CERTIFICATE environment variable.
• -s SERIAL, --hex-serial=SERIAL — same idea, but the serial number is in hexadecimal form, if one can't be read from the CERTMONGER_CERTIFICATE environment variable.
• -S STATE, --state=STATE — a cookie value handed over by a previous instance of this helper, for when the helper is being asked to continue a multi-step enrollment process. if the CERTMONGER_COOKIE environment variable is set, its value is used instead. 🍪
• -T NAME, --profile=NAME — the name of the type of certificate the client should request from the CA, if it's not renewing a certificate (per the -s option above). if the CERTMONGER_CA_PROFILE environment variable is set, its value is used. otherwise the default value is caServerCert.
• -O param=value, --approval-options=param=value — an extra parameter to pass to the server when approving the signing request using agent credentials. by default, any server-supplied default settings are applied. you can use this either to override a server-supplied default setting, or to supply one that otherwise wouldn't have been used. requires the -A option.
• -N, --force-new — even if an already-issued certificate is sitting in the CERTMONGER_CERTIFICATE environment variable, or a serial number has been provided, don't attempt to renew a certificate using its serial number. instead, attempt to obtain a new certificate using the signing request. the default behavior is to request a renewal if possible.
• -R, --force-renew — negates the effect of the -N flag. it's the "actually, no, go back" button 💅
• -t, --profile-list — instead of attempting to obtain a new certificate, query the server for a list of the enabled enrollment profiles. window shopping, iconic.
• -o param=value, --submit-option=param=value — when initially submitting a request to the CA, add the specified parameter and value along with any request parameters that would otherwise be sent.
• -a, --agent-submit — use agent credentials (specified using some combination of the -d, -n, -c, and -k flags) to authenticate to the CA when initially submitting a request to the CA, or when retrieving the list of enabled enrollment profiles. this is typically required when the enrollment profile being used uses AgentCertAuth-based authentication, and requires that the URL specified using the -E flag be an HTTPS URL, or when the URL specified using the -E flag is an HTTPS URL.
• -u username, --uid=username — when initially submitting a request to the CA, supply the specified value as a user name. this is typically required when the enrollment profile being used uses UidPwdDirAuth-based or NISAuth-based authentication.
• -U userdn, --upn=userdn — when initially submitting a request to the CA, supply the specified value as the DN (distinguished name) of the user's entry in a directory server which the CA is configured to use for checking the user's password. this is typically required when the enrollment profile being used uses UdnPwdDirAuth-based authentication.
• -W PASSWORD, --userpwd=PASSWORD — when initially submitting a request to the CA, supply the specified value as the password for the user whose name is specified with the -u option, or whose DN is specified with the -U option. this is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. ⚠️ if the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.
• -w FILE, --userpwdfile=FILE — when initially submitting a request to the CA, read a password from the specified file and supply it for the user whose name is specified with the -u option, or whose DN is specified with the -U option. this is typically only required when the enrollment profile being used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or NISAuth-based authentication. ⚠️ if the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.
• -Y PIN, --userpin=PIN — when initially submitting a request to the CA, supply the specified value as the PIN for the user whose name is specified with the -u option, or whose DN is specified with the -U option. this is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. ⚠️ if the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.
• -y FILE, --userpinfile=FILE — when initially submitting a request to the CA, read a PIN from the specified file and supply it for the user whose name is specified with the -u option, or whose DN is specified with the -U option. this is typically only required when the enrollment profile being used uses UidPwdPinDirAuth-based authentication. ⚠️ if the URL specified using the -E flag is not an HTTPS URL, this value will not be encrypted.
• -v, --verbose — bumps the logging level up. use it twice for even more logging. this one is mainly useful for troubleshooting, i.e. when everything is on fire and you need the receipts 🔥

👑 AGENT KEY AND CERTIFICATE OPTIONS 👑

these are the options that give the location for the private key and public certificate the client should use to authenticate to the CA's agent interface. which values you use depends on which cryptography library your copy of libcurl was linked with — iykyk.

• -d DIR, --dbdir=DIR — use an NSS database in the specified directory for this certificate and key. only valid with -n.
• -n NAME, --nickname=NAME — use the NSS key with this nickname. only valid with -d.
• -c FILE, --certfile=FILE — the PEM file that contains the public certificate. only valid with -k.
• -k FILE, --keyfile=FILE — the PEM file that contains the private certificate. only valid with -c.
• -p FILE, --sslpinfile=FILE — the name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.
• -P PIN, --sslpin=PIN — the name of a file which contains a PIN/password which will be needed in order to make use of the agent credentials.

🌈 EXIT STATUS 🌈

• 0 — if the certificate was issued. the certificate will be printed. 🎉 slay.
• 1 — if the CA is still thinking. a cookie (state) value will be printed. 🍪
• 2 — if the CA rejected the request. an error message may be printed. 💀
• 3 — if the CA was unreachable. an error message may be printed.
• 4 — if critical configuration information is missing. an error message may be printed.
• 5 — if the CA is still thinking. a suggested poll delay (specified in seconds) and a cookie (state) value will be printed. ⏳
• 17 — if the CA indicates that the client needs to attempt enrollment using a new key pair. 🔑✨

🙈 BUGS 🙈

found one? please file tickets for any that you find at https://fedorahosted.org/certmonger/ — the maintainers want the tea, fr fr.

💜 SEE ALSO 💜

certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1) getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-refresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1) getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1) getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmonger-dogtag-ipa-renew-agent-submit(8) certmonger-ipa-submit(8) certmonger-local-submit(8) certmonger-scep-submit(8) certmonger_selinux(8)

and that's the whole page bestie 🎀 this one came from the certmonger Manual, it's dated October 27, 2015, and its manual page name is CERTMONGER(8). go forth, renew those certs, and stay encrypted 💖✨🦋