1CERTMONGER(8) System Manager's Manual CERTMONGER(8)
2
6 dogtag-ipa-renew-agent-submit
7
10 dogtag-ipa-renew-agent-submit [options] [csrfile]
11
15 dogtag-ipa-renew-agent-submit is the helper which certmonger uses to
16 make certificate renewal requests to Dogtag instances running on IPA
17 servers. It is not normally run interactively, but it can be for trou‐
18 bleshooting purposes.
19 The preferred option is to request a renewal of an already-issued cer‐
21 tificate, using its serial number, which can be read from a PEM-format‐
22 ted certificate provided in the CERTMONGER_CERTIFICATE environment
23 variable, or via the -s or -D option on the command line. If no serial
24 number is provided, then the client will attempt to obtain a new cer‐
25 tificate by submitting a signing request to the CA.
26 The signing request which is to be submitted should either be in a file
28 whose name is given as an argument, or fed into dogtag-ipa-re‐
29 new-agent-submit via stdin.
30 certmonger does not yet support retrieving trust information from Dog‐
32 tag CAs.
33
36 -E EE-URL, --ee-url=EE-URL
37 The top-level URL for the end-entity interface provided by the
38 CA. In IPA installations, this is typically
39 http://SERVER:EEPORT/ca/ee/ca. If no URL is specified, the host
40 named in the [global] section in the /etc/ipa/default.conf file
41 is used as the value of SERVER, and the value of EEPORT will be
42 inferred based on the value of the dogtag_version in the
43 [global] section in the /etc/ipa/default.conf file: if dog‐
44 tag_version is set to 10 or more, EEPORT will be set to 8080.
45 Otherwise it will be 9180.
46 -A AGENT-URL, --agent-url=AGENT-URL
48 The top-level URL for the agent interface provided by the CA.
49 In IPA installations, this is typically https://SERVER:AGENT‐
50 PORT/ca/agent/ca. If no URL is specified, the host named in the
51 [global] section in the /etc/ipa/default.conf file is used as
52 the value of SERVER, and the value of AGENTPORT will be inferred
53 based on the value of the dogtag_version in the [global] section
54 in the /etc/ipa/default.conf file: if dogtag_version is set to
55 10 or more, AGENTPORT will be set to 8443. Otherwise it will be
56 9443.
57 -i FILE, --cafile=PATH
59 The location of a file containing a copy of the CA's certifi‐
60 cate, against which the CA server's certificate will be veri‐
61 fied. The default is /etc/ipa/ca.crt.
62 -C DIR, --capath=DIR
64 The location of a directory containing a copy of the CA's cer‐
65 tificate, against which the CA server's certificate will be ver‐
66 ified.
67 -d DIR, --dbdir=DIR
69 The NSS database that contains credentials to authenticate to
70 the CA.
71 -n NAME, --nickname=NAME
73 The nickname of the certificate used for authentication.
74 -c FILENAME, --certfile=FILENAME
76 The certificate in PEM format used for authentication.
77 -k FILENAME, --keyfile=FILENAME
79 The private key for the certificate in PEM format used for au‐
80 thentication. It may be encrypted.
81 -p FILENAME, --sslpinfile=FILENAME
83 A file that contains the pin for the private key file or NSS
84 database.
85 -P STRING, --sslpin=STRING
87 The pin for the private key file or NSS database.
88 -s NUMBER, --hex-serial=NUMBER
90 The serial number of an already-issued certificate for which the
91 client should attempt to obtain a new certificate, in hexideci‐
92 mal form, if one can not be read from the CERTMONGER_CERTIFICATE
93 environment variable.
94 -D NUMBER, --serial=NUMBER
96 The serial number of an already-issued certificate for which the
97 client should attempt to obtain a new certificate, in decimal
98 form, if one can not be read from the CERTMONGER_CERTIFICATE en‐
99 vironment variable.
100 -S STATE-VALUE, --state=STATE-VALUE
102 A cookie value provided by a previous instance of this helper,
103 if the helper is being asked to continue a multi-step enrollment
104 process. If the CERTMONGER_COOKIE environment variable is set,
105 its value is used.
106 -T NAME, --profile=NAME
108 The name of the type of certificate which the client should re‐
109 quest from the CA if it is not renewing a certificate (per the
110 -s option above). If the CERTMONGER_CA_PROFILE environment
111 variable is set, its value is used. Otherwise, the default
112 value is caServerCert.
113 -t, --profile-list
115 Instead of attempting to obtain a new certificate, query the
116 server for a list of the enabled enrollment profiles.
117 -O param=value, --approval-option=param=value
119 An additional parameter to pass to the server when approving the
120 signing request using the agent's credentials. By default, any
121 server-supplied default settings are applied. This option can
122 be used either to override a server-supplied default setting, or
123 to supply one which would otherwise have not been used.
124 -N, --force-new
126 Even if an already-issued certificate is available in the CERT‐
127 MONGER_CERTIFICATE environment variable, or a serial number has
128 been provided, don't attempt to renew a certificate using its
129 serial number. Instead, attempt to obtain a new certificate us‐
130 ing the signing request. The default behavior is to request a
131 renewal if possible.
132 -R, --force-renew
134 Negates the effect of the -N flag.
135 -o param=value, --submit-option=param=value
137 When initially submitting a request to the CA, add the specified
138 parameter and value along with any request parameters which
139 would otherwise be sent. This option is not typically used.
140 -a, --agent-submit
142 Use agent credentials, specified using some combination of the
143 -d, -n, -c, and -k flags, to authenticate to the CA when ini‐
144 tially submitting a request to the CA or retrieving the list of
145 enabled enrollment profiles. This is typically required when
146 the enrollment profile being used uses AgentCertAuth-based au‐
147 thentication, and requires that the URL specified using the -E
148 flag be an HTTPS URL, or when the URL specified using the -E
149 flag is an HTTPS URL.
150 -u username, --uid=username
152 When initially submitting a request to the CA, supply the speci‐
153 fied value as a user name. This is typically required when the
154 enrollment profile being used uses UidPwdDirAuth-based or
155 NISAuth-based authentication..TP -U userdn, --upn=userdn When
156 initially submitting a request to the CA, supply the specified
157 value as the DN (distinguished name) of the user's entry in a
158 directory server which the CA is configured to use for checking
159 the user's password. This is typically required when the en‐
160 rollment profile being used uses UdnPwdDirAuth-based authentica‐
161 tion.
162 -W PASSWORD, --userpwd=PASSWORD
164 When initially submitting a request to the CA, supply the speci‐
165 fied value as the password for the user whose name is specified
166 with the -u option, or whose DN is specified with the -U option.
167 This is typically only required when the enrollment profile be‐
168 ing used uses UidPwdDirAuth-based, UserPwdDirAuth-based, or
169 NISAuth-based authentication. If the URL specified using the -E
170 flag is not an HTTPS URL, this value will not be encrypted.
171 -w FILE, --userpwdfile=FILE
173 When initially submitting a request to the CA, read from the
174 specified file a password to supply for the user whose name is
175 specified with the -u option, or whose DN is specified with the
176 -U option. This is typically only required when the enrollment
177 profile being used uses UidPwdDirAuth-based, UserPwdDi‐
178 rAuth-based, or NISAuth-based authentication. If the URL speci‐
179 fied using the -E flag is not an HTTPS URL, this value will not
180 be encrypted.
181 -Y PIN, --userpin=PIN
183 When initially submitting a request to the CA, supply the speci‐
184 fied value as the PIN for the user whose name is specified with
185 the -u option, or whose DN is specified with the -U option.
186 This is typically only required when the enrollment profile be‐
187 ing used uses UidPwdPinDirAuth-based authentication. If the URL
188 specified using the -E flag is not an HTTPS URL, this value will
189 not be encrypted. -y FILE, --userpinfile=FILE When initially
190 submitting a request to the CA, read from the specified file a
191 PIN to supply for the user whose name is specified with the -u
192 option, or whose DN is specified with the -U option. This is
193 typically only required when the enrollment profile being used
194 uses UidPwdPinDirAuth-based authentication. If the URL speci‐
195 fied using the -E flag is not an HTTPS URL, this value will not
196 be encrypted.
197 -v, --verbose
199 Increases the logging level. Use twice for more logging. This
200 option is mainly useful for troubleshooting.
201
203 Options that provide the location for the private key and public cer‐
204 tificate which the client should use to authenticate to the CA's agent
205 interface. The values to use depend on which cryptography library your
206 copy of libcurl was linked with.
207 The location of the certificate used for authentication to the CA needs
209 to be provided in either a combination of PEM files using --certfile
210 and --keyfile or an NSS database using--dbdir and --nickname. The de‐
211 fault for --cafile is /etc/ipa/ca.crt.
212 -d dbdir, --dbdir=dbdir
214 Use an NSS database in the specified directory for this certifi‐
215 cate and key. Only valid with -n.
216 -n NAME, --nickname=NAME
218 Use the NSS key with this nickname. Only valid with -d.
219 -c FILE, --certfile=FILE
221 The PEM file that contains the public certificate. Only valid
222 with -k.
223 -k FILE, --keyfile=FILE
225 The PEM file that contains the private certificate. Only valid
226 with -c.
227 -p FILE, --sslpinfile=FILE
229 The name of a file which contains a PIN/password which will be
230 needed in order to make use of the agent credentials.
231 -P PIN, --sslpin=PIN
233 The name of a file which contains a PIN/password which will be
234 needed in order to make use of the agent credentials.
235
237 0 if the certificate was issued. The certificate will be printed.
238 1 if the CA is still thinking. A cookie (state) value will be
240 printed.
241 2 if the CA rejected the request. An error message may be
243 printed.
244 3 if the CA was unreachable. An error message may be printed.
246 4 if critical configuration information is missing. An error mes‐
248 sage may be printed.
249 5 if the CA is still thinking. A suggested poll delay (specified
251 in seconds) and a cookie (state) value will be printed.
252 17 if the CA indicates that the client needs to attempt enrollment
254 using a new key pair.
255
258 /etc/ipa/default.conf
259 is the IPA client configuration file. This file is consulted to
260 determine the URL for the Dogtag server's end-entity and agent
261 interfaces if they are not supplied as arguments.
262
265 Please file tickets for any that you find at https://fedora‐
266 hosted.org/certmonger/
267
270 certmonger(8) getcert(1) getcert-add-ca(1) getcert-add-scep-ca(1)
271 getcert-list-cas(1) getcert-list(1) getcert-modify-ca(1) getcert-re‐
272 fresh-ca(1) getcert-refresh(1) getcert-rekey(1) getcert-remove-ca(1)
273 getcert-resubmit(1) getcert-start-tracking(1) getcert-status(1)
274 getcert-stop-tracking(1) certmonger-certmaster-submit(8) certmon‐
275 ger-dogtag-submit(8) certmonger-ipa-submit(8) certmonger-local-sub‐
276 mit(8) certmonger-scep-submit(8) certmonger_selinux(8)
277certmonger Manual October 27, 2015 CERTMONGER(8)