1kmfcfg(1)                        User Commands                       kmfcfg(1)
2
3
4

NAME

6       kmfcfg - Key Management Policy and Plugin Configuration Utility
7

SYNOPSIS

9       kmfcfg subcommand [option ...]
10
11

DESCRIPTION

13       The  kmfcfg  command allows users to configure Key Management Framework
14       (KMF) policy databases. The KMF policy database (DB) restricts the  use
15       of keys and certificates that are managed through the KMF framework.
16
17
18       kmfcfg provides the ability to list, create, modify, delete, import and
19       export policy definitions either in the system  default  database  file
20       /etc/security/kmfpolicy.xml or a user-defined database file.
21
22
23       For  plugin configuration, kmfcfg allows users to display plugin infor‐
24       mation, install or uninstall  a  KMF  plugin,  and  modify  the  plugin
25       option.
26

SUBCOMMANDS

28       The following subcommands are supported:
29
30       create
31
32           Adds a new policy into the policy database file.
33
34           The format for the create subcommand is as follows:
35
36             create [dbfile=dbfile] policy=policyname
37                 [ignore-date=true|false]
38                 [ignore-unknown-eku=true|false]
39                 [ignore-trust-anchor=true|false]
40                 [validity-adjusttime=adjusttime]
41                 [ta-name=trust anchor subject DN]
42                 [ta-serial=trust anchor serial number]
43                 [ocsp-responder=URL]
44                 [ocsp-proxy=URL]
45                 [ocsp-use-cert-responder=true|false]
46                 [ocsp-response-lifetime=timelimit]
47                 [ocsp-ignore-response-sign=true|false]
48                 [ocsp-responder-cert-name=Issuer DN]
49                 [ocsp-responder-cert-serial=serial number]
50                 [crl-basefilename=basefilename]
51                 [crl-directory=directory]
52                 [crl-get-crl-uri=true|false]
53                 [crl-proxy=URL]
54                 [crl-ignore-crl-sign=true|false]
55                 [crl-ignore-crl-date=true|false]
56                 [keyusage=digitalSignature|nonRepudiation
57                           |keyEncipherment | dataEncipherment |
58                           keyAgreement |keyCertSign |
59                           cRLSign | encipherOnly | decipherOnly],[...]
60                 [ekunames=serverAuth | clientAuth |
61                          codeSigning | emailProtection |
62                          ipsecEndSystem | ipsecTunnel |
63                          ipsecUser | timeStamping |
64                          OCSPSigning],[...]
65                 [ekuoids=OID,OID,OID...]
66
67
68           The create subcommand supports the following options:
69
70           crl-basefilename=filename
71           crl-directory=directory
72
73               These  two  attributes are used to specify the location for CRL
74               files. The crl-basefilename attribute represents the base file‐
75               name for a CRL file. The crl-directory attribute represents the
76               directory for CRL files, which defaults to the  current  direc‐
77               tory.
78
79               If  the  crl-get-crl-uri  attribute is set to true and the crl-
80               basefilename is not specified, the basefilename for the  cached
81               CRL file is the basename of the URI used to fetch the CRL file.
82
83               If  the crl-get-crl-uri attribute is set to false the crl-base‐
84               filename needs to be specified to indicate an input  CRL  file.
85               The setting for crl-get-crl-uri is false by default.
86
87               These  two attributes only apply to the file-based CRL plugins.
88               The current file-based CRL plugins are  file  and  pkcs11  key‐
89               stores.  For  the  nss keystore, the CRL location is always the
90               NSS internal database.
91
92
93           crl-get-crl-uri=true | false
94
95               Configure if a CRL file is fetched and  cached  dynamically  as
96               part  of  the certificate validation, using the URI information
97               from the certificate's distribution points extension.
98
99               The default for this attribute is false.
100
101
102           crl-ignore-crl-date=true | false
103
104               If crl-ignore-crl-date is set to true, the validity time period
105               of the CRL is not checked.
106
107               The default for this attribute is false.
108
109
110           crl-ignore-crl-sign=true | false
111
112               If crl-ignore-crl-sign is set to true, the signature of the CRL
113               is not checked.
114
115               The default for this attribute is false.
116
117
118           crl-proxy= URL
119
120               Sets the proxy server name and port for dynamically  retrieving
121               a CRL file when crl-get-crl-uri is set to true.
122
123               The  port  number is optional. If the port number is not speci‐
124               fied, the default value is 8080. An example  crl-proxy  setting
125               might be: crl-proxy=webcache.sfbay:8080.
126
127
128           dbfile=dbfile
129
130               The  DB  file  to  add  the  new  policy. If not specified, the
131               default is the  system  KMF  policy  database  file  /etc/secu‐
132               rity/kmfpolicy.xml.
133
134
135           ekuoids=EKUOIDS
136
137               A  comma  separated  list  of  Extended Key Usage OIDs that are
138               required by the policy being defined. The OIDs are expressed in
139               dot  notation, for example, 1.2.3.4. An example ekuoids setting
140               might be: ekuoids=1.2.3.4,9.8.7.6.5.
141
142
143           ekunames=EKUNAMES
144
145               A comma separated list of Extended Key  Usage  names  that  are
146               required  by  the  policy  being  defined.  The  list of values
147               allowed for EKUNAMES are: serverAuth, clientAuth,  codeSigning,
148               emailProtection, ipsecEndSystem, ipsecTunnel, ipsecUser, timeS‐
149               tamping, and OCSPSigning
150
151               The OCSP, CRL, key usage and extended key usage  checkings  are
152               off by default. To turn on any one of them, specify one or more
153               attributes for the particular checking.  For  example,  if  the
154               ocsp-responder  attribute  is  set,  then  the OCSP checking is
155               turned on. If the ekuname attribute or the ekuoids attribute is
156               set, then the extended key usage checking is turned on.
157
158
159           ignore-date=true | false
160
161               Set  the  Ignore  Date  option for this policy. By default this
162               value is false. If true is specified, the  policy  ignores  the
163               validity  periods  defined  in the certificates when evaluating
164               their validity.
165
166
167           ignore-unknown-eku=true | false
168
169               Set the Ignore Unknown EKU option for this policy.  By  default
170               this  value  is false. If true, the policy ignores any unrecog‐
171               nized EKU values in the Extended Key Usage extension.
172
173
174           ignore-trust-anchor=true | false
175
176               Set the Ignore Trust Anchor option for this policy. By  default
177               this  value is false. If true is specified, the policy does not
178               verify the signature of the  subject  certificate  using  trust
179               anchor certificate at validation.
180
181
182           keyusage=KUVALUES
183
184               A comma separated list of key usage values that are required by
185               the policy being defined. The list of values allowed are: digi‐
186               talSignature,  nonRepudiation,  keyEncipherment,  dataEncipher‐
187               ment, keyAgreement, keyCertSign, cRLSign,  encipherOnly,  deci‐
188               pherOnly
189
190
191           ocsp-ignore-response-sign=true | false
192
193               If  this  attribute  is  set to true, the signature of the OCSP
194               response is not verified. This attribute value  is  default  to
195               false.
196
197
198           ocsp-proxy=URL
199
200               Set the proxy server name and port for OCSP. The port number is
201               optional. If the port number  is  not  specified,  the  default
202               value  is  8080.  An example ocsp-proxy setting might be: ocsp-
203               proxy="webcache.sfbay:8080"
204
205
206           ocsp-response-lifetime=timelimit
207
208               Set the freshness period that a response must be. The timelimit
209               can  be specified by number-day, number-hour, number-minute, or
210               number-second. An example ocsp-response-lifetime setting  might
211               be:ocsp-response-lifetime=6-hour.
212
213
214           ocsp-responder-cert-name=IssuerDN
215           ocsp-responder-cert-serial=serialNumber
216
217               These  two attributes represent the OCSP responder certificate.
218               The ocsp-responder-cert-name is to specify the issuer  name  of
219               the  certificate. See the ta-name option for example. The ocsp-
220               responder-cert-serial is for the  serial  number  and  must  be
221               specified      as     a     hex     value,     for     example,
222               0x0102030405060708090a0b0c0d0e0f. If an OCSP responder is  dif‐
223               ferent  from  the  issuer  of  the  certificate and if the OCSP
224               response needs to be verified, an  OCSP  responder  certificate
225               information should be provided.
226
227
228           ocsp-responder=URL
229
230               Set  the  OCSP  responder  URL for use with the OCSP validation
231               method.           For           example,           ocsp-respon‐
232               der=http://ocsp.verisign.com/ocsp/status
233
234
235           ocsp-use-cert-responder=true | false
236
237               Configure  this  policy  to always use the responder defined in
238               the certificate itself if possible.
239
240
241           policy=policyname
242
243               The policy record to be created. policyname is required.
244
245
246           validity-adjusttime=adjusttime
247
248               Set the adjust time for both ends of validity period for a cer‐
249               tificate. The time can be specified by number-day, number-hour,
250               number-minute, or number-second. An example validity-adjusttime
251               setting  might be: validity-adjusttime=6-hour. ta-name="Subject
252               DN" ta-serial=serialNumber
253
254               These two attributes represent the trust anchor certificate and
255               are  used to find the trust anchor certificate in the keystore.
256               The ta-name is to specify the distinguished name of  the  trust
257               anchor  certificate  subject  name. For example, ta-name="O=Sun
258               Microsystems Inc.,   OU=Solaris  Security  Technologies  Group,
259                L=Ashburn,  ST=VA,  C=US,  CN=John Smith" The serial number of
260               the TA certificate. This, along with the Issuer DN, is used  to
261               find the TA certificate in the keystore. The serial number must
262               be    specified    as    a    hex    value,    for     example,
263               0x0102030405060708090a0b0c0d0e The trust anchor attributes need
264               to be set, if the value  of  ignore-trust-anchor  attribute  is
265               false.
266
267
268
269       delete
270
271           Deletes  any  policy matching the indicated policy name. The system
272           default policy (default) cannot be deleted.
273
274           The format for the delete subcommand is as follows:
275
276             delete [dbfile=dbfile] policy=policyname
277
278
279           The delete subcommand supports the following options:
280
281           dbfile=dbfile        Read policy  definitions  from  the  indicated
282                                file.  If  dbfile  is  not  specified,  ,  the
283                                default is  the  system  KMF  policy  database
284                                file: /etc/security/kmfpolicy.xml.
285
286
287           policy=policyname    The  name  of the policy to delete. policyname
288                                is required, if using the system database.
289
290
291
292       export
293
294           Exports a policy from one policy database file  to  another  policy
295           database file.
296
297           The format for the export subcommand is as follows:
298
299             kmfcfg export policy=policyname outfile=newdbfile [dbfile=dbfile]
300
301
302           The export subcommand supports the following options:
303
304           dbfile=dbfile           The  DB  file  where the exported policy is
305                                   read.  If  dbfile  is  not  specified,  the
306                                   default  is  the system KMF policy database
307                                   file: /etc/security/kmfpolicy.xml.
308
309
310           outfile=outputdbfile    The DB file where the  exported  policy  is
311                                   stored.
312
313
314           policy=policyname       The policy record to be exported.
315
316
317
318       help
319
320           Displays help for the kmfcfg command.
321
322           The format for the help subcommand is as follows:
323
324             help
325
326
327
328
329       import
330
331           Imports  a  policy  from one policy database file to another policy
332           database file.
333
334           The format for the import subcommand is as follows:
335
336             kmfcfg import policy=policyname infile=inputdbfile [dbfile=dbfile]
337
338
339           The import subcommand supports the following options:
340
341           policy=policyname     The policy record to be imported.
342
343
344           infile=inputdbfile    The DB file to read the policy from.
345
346
347           dbfile=outdbfile      The DB file to add the  new  policy.  If  not
348                                 specified, the default is the system KMF pol‐
349                                 icy   database   file   /etc/security/kmfpol‐
350                                 icy.xml.
351
352
353
354       list
355
356           Without  arguments,  lists  all policy definitions from the default
357           system database.
358
359           The format for the list subcommand is as follows:
360
361             list [dbfile=dbfile] [policy=policyname]
362
363
364           The list subcommand supports the following options:
365
366           dbfile=dbfile        Reads policy definitions  from  the  indicated
367                                file.  If  not  specified,  the default is the
368                                system KMF  policy  database  file  /etc/secu‐
369                                rity/kmfpolicy.xml.
370
371
372           policy=policyname    Only  display  policy definition for the named
373                                policy.
374
375
376
377       modify
378
379           Modifies any policy matching the indicated name. The system default
380           policy (default) cannot be modified.
381
382           The format for the modify subcommand is as follows:
383
384             modify [dbfile=dbfile] policy=policyname
385                 [ignore-date=true|false]
386                 [ignore-unknown-eku=true|false]
387                 [ignore-trust-anchor=true|false]
388                 [validity-adjusttime=adjusttime]
389                 [ta-name=trust anchor subject DN]
390                 [ta-serial=trust anchor serial number]
391                 [ocsp-responder=URL]
392                 [ocsp-proxy=URL]
393                 [ocsp-use-cert-responder=true|false]
394                 [ocsp-response-lifetime=timelimit]
395                 [ocsp-ignore-response-sign=true|false]
396                 [ocsp-responder-cert-name=Issuer DN]
397                 [ocsp-responder-cert-serial=serial number]
398                 [ocsp-none=true|false]
399                 [crl-basefilename=basefilename]
400                 [crl-directory=directory]
401                 [crl-get-crl-uri=true|false]
402                 [crl-proxy=URL]
403                 [crl-ignore-crl-sign=true|false]
404                 [crl-ignore-crl-date=true|false]
405                 [crl-none=true|false]
406                 [keyusage=digitalSignature| nonRepudiation
407                           |keyEncipherment | dataEncipherment |
408                           keyAgreement |keyCertSign |
409                           cRLSign | encipherOnly | decipherOnly],[...]
410                 [keyusage-none=true|false]
411                 [ekunames=serverAuth | clientAuth |
412                          codeSigning | emailProtection |
413                          ipsecEndSystem | ipsecTunnel |
414                          ipsecUser | timeStamping |
415                          OCSPSigning],[...]
416                 [ekuoids=OID,OID,OID]
417                 [eku-none=true|false]
418
419
420           The modify subcommand supports many of the same options as the cre‐
421           ate subcommand. For descriptions of shared options, see the  create
422           subcommand.
423
424           The modify subcommand supports the following unique options:
425
426           crl-none=true | false         If  crl-none  is  set  to  true,  CRL
427                                         checking  is  turned  off.  If   this
428                                         attribute  is  set to true, other CRL
429                                         attributes cannot be set.
430
431
432           dfile=[dbfile]                The database file to modify a policy.
433                                         If  not specified, the default is the
434                                         system  KMF  policy   database   file
435                                         /etc/security/kmfpolicy.xml.
436
437
438           eku-none=true | false         If  eku-none is set to true, extended
439                                         key usage checking is turned off. The
440                                         extended  key  usage attributes, eku‐
441                                         name and ekuoids cannot be set at the
442                                         same time if eku-none is set to true.
443
444
445           keyusage-none=true | false    If  keyusage-none is set to true, key
446                                         usage checking is turned off.
447
448                                         The keyusage attribute cannot be  set
449                                         at the same time if this attribute is
450                                         set to true.
451
452
453           ocsp-none=true | false        If ocsp-none is  set  to  true,  OCSP
454                                         checking  is  turned  off.  Any other
455                                         OCSP attribute is not set at the same
456                                         time  if  this  attribute  is  set to
457                                         true.
458
459
460           policy=policyname             The name of  the  policy  to  modify.
461                                         policyname  is  required. Thedefault‐
462                                         policy in the system KMF policy data‐
463                                         base cannot be modified.
464
465
466
467   Plugin Subcommands
468       install keystore=keystore_name modulepath=pathname\ [option=option_str]
469
470           Install  a  plugin  into the system. The modulepath field specifies
471           the pathname to a KMF plugin shared library object. If pathname  is
472           not  specified  as an absolute pathname, shared library objects are
473           assumed to be relative to /lib/security/$ISA/.  The  ISA  token  is
474           replaced  by an implementation defined directory name which defines
475           the pathname relative to  the  calling  program's  instruction  set
476           architecture.
477
478
479       list plugin
480
481           Display KMF plugin information.
482
483           Without the pluginkeyword, kmfcfg list shows the policy information
484           as described in the SUBCOMMANDS section.
485
486
487       modify plugin keystore=keystore_name option=option_str
488
489           Modify the plugin option. The plugin option is defined by the plug‐
490           in  and  is  interpreted by the plugin specifically, therefore this
491           command accepts any option string.
492
493           Without the plugin keyword, kmfcfg modify updates the  policy  con‐
494           figuration as described in the SUBCOMMANDS section.
495
496
497       uninstall keystore=keystore_name
498
499           Uninstall the plugin with the keystore_name.
500
501

EXAMPLES

503       Example 1 Creating a New Policy
504
505
506       The  following  example creates a new policy called IPSEC in the system
507       database:
508
509
510         $ kmfcfg create IPSEC \
511         ignore-trust-anchor=true \
512         ocsp-use-cert-responder=true \
513         keyusage=keyAgreement,keyEncipherment,dataEncipherment \
514         ekuname=ipsecTunnel,ipsecUser
515
516
517

EXIT STATUS

519       The following exit values are returned:
520
521       0     Successful completion.
522
523
524       >0    An error occurred.
525
526

FILES

528       /etc/security/kmfpolicy.xml
529
530           Default system policy database
531
532

ATTRIBUTES

534       See attributes(5) for descriptions of the following attributes:
535
536
537
538
539       ┌─────────────────────────────┬─────────────────────────────┐
540       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
541       ├─────────────────────────────┼─────────────────────────────┤
542       │Availability                 │SUNWcsu                      │
543       ├─────────────────────────────┼─────────────────────────────┤
544       │Interface Stability          │Uncommitted                  │
545       └─────────────────────────────┴─────────────────────────────┘
546

SEE ALSO

548       attributes(5)
549
550
551
552SunOS 5.11                        3 Feb 2009                         kmfcfg(1)
Impressum