1CERTMONGER(8)               System Manager's Manual              CERTMONGER(8)
2
3
4

NAME

6       dogtag-ipa-renew-agent-submit
7
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

AGENT KEY AND CERTIFICATE OPTIONS

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

EXIT STATUS

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

FILES

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

BUGS

250       Please  file  tickets  for  any  that  you  find   at   https://fedora
251       hosted.org/certmonger/
252
253

SEE ALSO

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)
Impressum