rhn-ssl-tool(1)

1RHN-SSL-TOOL(1)                                                RHN-SSL-TOOL(1)
2
3
4

NAME

6       rhn-ssl-tool - Generate and maintain SSL keys, certificates and deploy‐
7       ment RPMs.
8

SYNOPSIS

10       rhn-ssl-tool [ options ... ] --help
11
12
13
14       rhn-ssl-tool --gen-ca -dBUILD_DIR -pCA_PASSWORD [ options ... ]
15
16
17
18       rhn-ssl-tool --gen-server -dBUILD_DIR -pCA_PASSWORD [ options ... ]
19
20

HELP

22       rhn-ssl-tool --help
23
24       rhn-ssl-tool --gen-ca --help
25
26       rhn-ssl-tool --gen-server --help
27
28       - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
29
30       (advanced) rhn-ssl-tool --gen-ca --key-only --help
31
32       (advanced) rhn-ssl-tool --gen-ca --cert-only --help
33
34       (advanced) rhn-ssl-tool --gen-ca --rpm-only --help
35
36       - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
37
38       (advanced) rhn-ssl-tool --gen-server --key-only --help
39
40       (advanced) rhn-ssl-tool --gen-server --cert-req-only --help
41
42       (advanced) rhn-ssl-tool --gen-server --cert-only --help
43
44       (advanced) rhn-ssl-tool --gen-server --rpm-only --help
45

DESCRIPTION

47       The RHN SSL Maintenance Tool (rhn-ssl-tool) is  used  to  generate  and
48       maintain  RHN SSL keys and certificates. It also will generate RPMs for
49       use in deploying these keys and certificates. The tool  is  geared  for
50       use in an RHN context, but can be useful outside of RHN.
51
52       Working with openssl directly can be tedious and trying. This tool aims
53       to make the process relatively simple. We  limit  the  scope  of  using
54       openssl to how we use it in RHN: securing web applications.
55
56       The  RHN  context  of this document is in support of RHN Satellite, but
57       all holds true for RHN Proxy as well, so keep that in  mind.  The  most
58       current  RHN Satellite Servers use /root/ssl-build as the default build
59       directory. Older RHN  Satellites  and  Proxies  used  the  /etc/syscon‐
60       fig/rhn/ssl  directory,  and *very* old installations used /etc/syscon‐
61       fig/rhn.
62
63       The basic process of  SSL  key/certificate/RPM  generation  using  this
64       tool: (step 1) generate a CA SSL key pair(set) and public RPM, (step 2)
65       create web server SSL key pair(set) and RPM (and tar archive).
66
67       Build directory structure: --dir BUILD_DIR is used with nearly all com‐
68       mandline  options.   BUILD_DIR  marks the top of the build tree; all CA
69       files and RPMs land there. Server SSL key pairs(sets) are FQDN specific
70       and so we build them in BUILD_DIR/MACHINE_NAME.
71
72       STEP 1: Generate a CA key pair(set) and public RPM:
73
74              rhn-ssl-tool --gen-ca --dir BUILD_DIR [ options ... ]
75
76              This step should ideally never need to be repeated unless the CA
77              password is lost or forgotten  (DON'T  DO  THAT!).  The  default
78              validity window for the CA is from now until 2038. The CA public
79              certificate is what get's distributed to clients of the  web-app
80              (RHN Satellite/Proxy).
81
82              In  the  RHN  Satellite/Proxy  context, the organization acts as
83              their own Certificate Authority, but these steps can be  skipped
84              if  intending  to use of an outside authority (This is not offi‐
85              cially supported by Red Hat).
86
87              The CA private key remains private.
88
89              The CA certificate is used by client software (up2date for exam‐
90              ple), and is generally deployed via an RPM or the raw file.
91
92       STEP 2: Generate a web server SSL key pair(set), RPM and tar
93
94              rhn-ssl-tool --gen-server --dir BUILD_DIR [ options ... ]
95
96              This  step  is  done  more frequently (generally), especially if
97              more than one RHN server is being  deployed  (--set-hostname  is
98              different  for each server). The default validity window for the
99              CA is from now until 2038. All clients using the CA  SSL  public
100              certificate  that signed the new web server SSL certificate will
101              work as expected with all web server key pairs(set) generated.
102
103              The web server SSL key and certificate are used  solely  by  the
104              web  application  server  (apache  on  an RHN Proxy or Satellite
105              Server for example).
106
107       A note about generated RPMs:
108              The --gen-ca process generates an RPM that contains  the  public
109              CA  certificate.  It  needs to be deployed to any clients making
110              SSL connections to an RHN server (RHN Satellite or Proxy).  This
111              is   generally   done   by  making  the  RPM  available  in  the
112              /var/www/html/pub directory. It is also a good idea to copy  the
113              CA  certificate  itself  in  that directory: RHN-ORG-TRUSTED-CA-
114              CERT.
115
116              The --gen-server process generates  an  RPM  that  contains  the
117              server.key and server.crt files needed to secure your RHN server
118              (RHN Satellite or RHN Proxy). It needs to be  installed  on  the
119              appropriate  server.  That  server then needs to have it's httpd
120              processes restarted /sbin/service httpd restart.
121
122       IMPORTANT:
123              Time and date need to be correctly set on  systems  establishing
124              SSL  connections.  It  is highly recommended that all client and
125              server systems have the ntpd service installed,  configured  and
126              running.
127
128       Advanced options (rarely used discete steps):
129
130              generate a CA SSL private key: --gen-ca --key-only ...
131
132              generate a CA SSL public certificate: --gen-ca --cert-only ...
133
134              generate a CA SSL public RPM: --gen-ca --rpm-only ...
135
136              generate a web server's SSL private key: --gen-server --key-only
137              ...
138
139              generate a web server's SSL  certificate  request:  --gen-server
140              --cert-req-only ...
141
142              generate/sign  a  web  server's  SSL  certificate:  --gen-server
143              --cert-only ...
144
145              generate a web server's private RPM (and tar  archive  used  for
146              RHN Proxy installations): --gen-server --rpm-only ...
147
148       Using a 3rd party CA (rarely done in the RHN context):
149
150              CA  public  certficate:  In the "3rd party CA" case, simply copy
151              the certificate authorities public certificate to the SSL  build
152              directory; renaming it to RHN-ORG-TRUSTED-SSL-CERT; and then run
153              --gen-ca --dir BUILD_DIR --rpm-only to package that  certificate
154              in  an  expected manner ready for client deployment.  NOTE: this
155              has not been tested by RHN personnell. See further  instructions
156              in step 2.
157
158              Web  server's  SSL  key  pair(set): Usually, one creates the web
159              server's SSL private key, certificate-request and certificate in
160              one  step. If using a 3rd party CA though, create a web server's
161              SSL private key and certificate-request via --gen-server  --key-
162              only  --dir  BUILD_DIR  and  --gen-server  --cert-req-only --dir
163              BUILD_DIR.  Have the 3rd party sign server.csr which will gener‐
164              ate  a  server.crt  file.  Copy  that  server.crt  file into the
165              BUILD_DIR/MACHINE_NAME directory (where the server.key file  was
166              generated).  And  then  create  your  deployable RPM with --gen-
167              server --rpm-only --dir BUILD_DIR.
168
169       NOTE: each step (--gen-* or --gen-* --*-only) has its own --help infor‐
170       mation.
171

ALL OPTIONS

173       -h | --help
174              Display the help screen with a list of base options (--gen-*).
175
176       --gen-ca
177              Generate a Certificate Authority (CA) key pair and public RPM:
178
179              -f | --force
180                     forcibly  create  a new CA private key and/or public cer‐
181                     tificate.
182
183              -pPASSWORD |
184                     CA password. Will prompt if option is missing.
185
186              -d BUILD_DIR |
187                     build directory (default: ./ssl-build).
188
189              --ca-key=FILENAME
190                     CA private key filename(default is dynamically set).
191
192              --ca-cert=FILENAME
193                     CA public certificate filename  (default  is  dynamically
194                     set).
195
196              --cert-expiration=CA_CERT_EXP
197                     expiration  of  public  CA certificate (default is # days
198                     until 1 day prior to epoch rollover (or 01-19-2038)).
199
200              --set-country=COUNTRY_CODE
201                     two letter country code (default: US).
202
203              --set-state=STATE_OR_PROVINCE
204                     state or province, such as "North Carolina" (default: "")
205
206              --set-city=CITY_OR_LOCALITY
207                     city or locality, such as "Raleigh" (default: "").
208
209              --set-org=ORGANIZATION
210                     organization or company  name  (default:  "Example  Corp.
211                     Inc").
212
213              --set-org-unit=ORGANIZATIONAL_UNIT
214                     organizational unit (default: unit).
215
216              --set-common-name=HOSTNAME
217                     not  generally  set  for  the  CA certificate. The common
218                     name.
219
220              --set-email=EMAIL
221                     email address. Not generally set for the CA certificate.
222
223              -v | --verbose
224                     be verbose (accumulative: -vvv means  "be  *really*  ver‐
225                     bose).
226
227              --key-only
228                     (rarely  used) only generate a CA private key. Try --gen-
229                     ca --key-only --help for more information.
230
231              --cert-only
232                     (rarely used) only generate a CA public certificate.  Try
233                     --gen-ca --cert-only --help for more information.
234
235              --ca-cert-rpm
236                     (rarely  changed)  RPM name that houses the CA SSL public
237                     certificate (the  base  filename,  not  filename-version-
238                     release.noarch.rpm).
239
240              --rpm-packager
241                     (rarely used) packager of the generated RPM, such as "RHN
242                     Admin <rhn-admin@example.com>".
243
244              --rpm-vendor
245                     (rarely used) vendor of the generated RPM, such as "IS/IT
246                     Example Corp.".
247
248              --rpm-only
249                     (rarely used) only generate a deployable RPM.  Try --gen-
250                     ca --rpm-only --help for more information.
251
252              --no-rpm
253                     (rarely used) do everything *except* generate an RPM.
254
255              -h | --help
256                     help message.
257
258       --gen-server
259              Generate a web server's SSL key pair(set), RPM and tar archive:
260
261              -pPASSWORD |
262                     CA password. Will prompt if option is missing. MUST MATCH
263                     PASSWORD OF CA!!!
264
265              -d BUILD_DIR |
266                     build directory (default: ./ssl-build).
267
268              --server-key=FILENAME
269                     web   server's   SSL   private   key  filename  (default:
270                     server.key).
271
272              --server-cert-req=FILENAME
273                     web server's SSL certificate request  filename  (default:
274                     server.csr).
275
276              --server-cert=FILENAME
277                     web   server's   SSL   certificate   filename   (default:
278                     server.crt).
279
280              --startdate=YYMMDDHHMMSSZ
281                     start date for web server's SSL certificate  validity  in
282                     the above format (Z is a letter; default is 1 week ago).
283
284              --cert-expiration=EXPIRATION
285                     expiration  of  the web server's SSL certificate (default
286                     is # days  until  1  day  prior  to  epoch  rollover  (or
287                     01-19-2038)).
288
289              --set-country=COUNTRY_CODE
290                     two letter country code (default: US).
291
292              --set-state=STATE_OR_PROVINCE
293                     state or province (default: "North Carolina")
294
295              --set-city=CITY_OR_LOCALITY
296                     city or locality (default: Raleigh).
297
298              --set-org=ORGANIZATION
299                     organization  or  company  name  (default: "Example Corp.
300                     Inc").
301
302              --set-org-unit=ORGANIZATIONAL_UNIT
303                     organizational unit, such as "Marketing" (default: unit).
304
305              --set-hostname=HOSTNAME
306                     set the hostname (FQDN: fully qualified domain  name)  of
307                     the  RHN Satellite or RHN Proxy (default: build machine's
308                     hostname).
309
310              --set-email=EMAIL
311                     email address (default: admin@example.com)
312
313              -v | --verbose
314                     be verbose (accumulative: -vvv means  "be  *really*  ver‐
315                     bose).
316
317              --key-only
318                     (rarely  used)  only  generate a web server's SSL private
319                     key. Try --gen-server --key-only --help for more informa‐
320                     tion.
321
322              --cert-req-only
323                     (rarely  used)  only generate a web server's SSL certifi‐
324                     cate request. Try --gen-server --cert-req-only --help for
325                     more information.
326
327              --cert-only
328                     (rarely  used)  only generate a web server's SSL certifi‐
329                     cate. Try --gen-server --cert-only --help for more infor‐
330                     mation.
331
332              --server-rpm
333                     (rarely  changed)  RPM  name that houses the web server's
334                     SSL key set (the  base  filename,  not  filename-version-
335                     release.noarch.rpm).
336
337              --server-tar
338                     (rarely  changed)  name  of  archive (tarball) of the web
339                     server's SSL key set and CA SSL public  certificate  that
340                     is  used solely by the hosted RHN Proxy installation rou‐
341                     tines   (the   base   filename,   not   filename-version-
342                     release.tar).
343
344              --rpm-packager
345                     (rarely used) packager of the generated RPM, such as "RHN
346                     Admin <rhn-admin@example.com>".
347
348              --rpm-vendor
349                     (rarely used) vendor of the generated RPM, such as "IS/IT
350                     Example Corp.".
351
352              --rpm-only
353                     (rarely used) only generate a deployable RPM.  Try --gen-
354                     server --rpm-only --help for more information.
355
356              --no-rpm
357                     (rarely used) do everything *except* generate an RPM.
358
359              -h | --help
360                     help message.
361

EXAMPLES

363       rhn-ssl-tool --help
364
365       rhn-ssl-tool --gen-ca --help
366
367       rhn-ssl-tool --gen-server --help
368
369       rhn-ssl-tool  --gen-ca  -pMY_CA_PASSWORD  --set-state="North  Carolina"
370       --set-city=Raleigh   --set-org="Example  Inc."  --set-org-unit="SSL  CA
371       Unit" --dir=/etc/sysconfig/rhn/ssl
372
373       rhn-ssl-tool --gen-server -pMY_CA_PASSWORD --set-state="North Carolina"
374       --set-city=Raleigh   --set-org="Example   Inc."  --set-org-unit="IS/IT"
375       --email="taw@example.com"          --set-hostname="rhnbox1.example.com"
376       --dir=/etc/sysconfig/rhn/ssl
377

FILES

379       BUILD_DIR/rhn-ca-openssl.cnf
380
381       BUILD_DIR/RHN-ORG-PRIVATE-SSL-KEY
382
383       BUILD_DIR/RHN-ORG-TRUSTED-SSL-CERT
384
385       BUILD_DIR/serial
386
387       BUILD_DIR/index.txt
388
389       BUILD_DIR/latest.txt
390
391       BUILD_DIR/rhn-org-trusted-ssl-cert-VER-REL.src.rpm
392
393       BUILD_DIR/rhn-org-trusted-ssl-cert-VER-REL.noarch.rpm
394
395       BUILD_DIR/MACHINE_NAME/latest.txt
396
397       BUILD_DIR/MACHINE_NAME/rhn-server-openssl.cnf
398
399       BUILD_DIR/MACHINE_NAME/server.key
400
401       BUILD_DIR/MACHINE_NAME/server.csr
402
403       BUILD_DIR/MACHINE_NAME/server.crt
404
405       BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-
406       REL.src.rpm
407
408       BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-key-pair-MACHINE_NAME-VER-
409       REL.noarch.rpm
410
411       BUILD_DIR/MACHINE_NAME/rhn-org-httpd-ssl-archive-MACHINE_NAME-VER-
412       REL.tar
413

AUTHOR

420       Todd Warner <taw@redhat.com>
421
422
423
424Version 1.0.0                   07 October 2010                RHN-SSL-TOOL(1)