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