Pegasus Enhancement Proposal (PEP)

PEP #: 259

Title: SSL Certificate Management Command Interfaces

Status: Approved

Version History:

Version

Date

Author

Change Description

1.0

May 12 2006

Sushma Fernandes

Initial Submittal

1.1

June 12 2006

Sushma Fernandes

Updated add and remove options.

1.2

June 13 2006

Sushma Fernandes

Addressed PEP review comments

Approved version

Abstract: The ssltrustmgr command line interface is not frozen. This is a proposal to cleanup, freeze this interface and add it to the external interface set.

Definition of the Problem

The ssltrustmgr command provides an interface to manage X509 certificates in a trust store or X509 Certificate Revocation Lists in a CRL store. To make this command available to the clients the interface needs to be reviewed, frozen and added to the external interface set.

Proposed Solution

The following changes are proposed in this PEP:

1.      Split the truststore management and CRL management functionality into two separate commands cimtrust and cimcrl. cimtrust command will provide an interface to manage X509 certificates in a truststore. cimcrl command will provide an interface to manage X509 CRLs in a CRL store.

2.      Update the command line usage information to make it consistent with current and proposed functionality. The following changes are proposed:

a.      Remove the –T trustpath option as it is not supported.

b.      Remove the –t truststore option. Use a single truststore for both CIM operation and CIM export requests.

c.       Change the certuser option to be optional.

3.      Currently, if a file containing multiple X509 certificates are specified, the add operation only adds the first certificate and returns success. It is proposed that if multiple certificates are specified in a file then the certificate should not be added and an error message be returned instead.

4.      Currently, the ssltrustmgr command returns 1 on error or 0 on success. Enhance cimtrust and cimcrl to return specific return codes on error.

5.      Remove configuration properties exportSSLTrustStore and enableSSLExportClientVerification.  This change will impact Config, Server, SSL related files in Common and CertificateProvider components.

The following files are affected by this proposal:

New files:

 

New test files:

 

Updated files:

 

Removed files:

 

Proposed cimtrust and cimcrl man pages:

cimtrust

NAME

cimtrust- add, remove or list X509 certificates in a PEM format trust store.

SYNOPSIS

cimtrust -a [ -U certuser ] -f file –T ( a | e | s )

cimtrust -r -i issuer ( -n serialnumber | -S subject )

cimtrust -l [ -i issuer [ -n serialnumber | -S subject ] ]

cimtrust --help

cimtrust --version

Remarks

The cimtrust command requires that the CIM Server is running.  This command operates on a trust store on the local system only.

DESCRIPTION

The add option of the cimtrust command adds an X509 certificate file of a specified type to the truststore. The certuser specifies the username to be associated with the certificate in the file. If no certuser is specified, the certificate may not be used to authenticate a user.

The remove option of the cimtrust command removes the X509 certificate(s) matching the specified issuer and either serialnumber or subject from the truststore.

The list option of the cimtrust command lists the X509 certificates in the truststore. The list can be filtered by issuer and either serialnumber or subject.

Certificates in the trust store may be revoked by adding a Certificate Revocation List to the CRL store. For more information on CRL operations see the cimcrl(1m)  command.

OPTIONS

cimtrust recognizes the following options:

-a

 

Adds a certificate to the  truststore. If the specified file does not contain a valid X509 certificate an error message is returned and no action is taken. If the X509 certificate already exists in the truststore, an error message is returned.

-r

 

Removes certificate(s) from the truststore. If the truststore contains multiple certificates matching the specified issuer and subject, all the matching certificates are removed. If no certificate exists for the specified issuer and either serialnumber or subject, an error message is returned and no action is taken. 

 

-l

 

Displays the X509 certificates in the truststore.

 

 

-f file

Specifies a PEM format file containing an X509 certificate.

 

 

-U certuser

Specifies a username to be associated with the specified certificate. The username specified should be a valid system user on the target system.

 

 

-i issuer

Specifies the issuer name for a certificate.

 

 

-n serialnumber

Specifies a certificate serial number.

 

 

-S subject

Specifies the subject name for a certificate.

 

 

-T type

Specifies the type of a certificate. The type must be one of the following:

 

1.    authority (a): root/intermediate authority certificates. Certificates of this type are added to the trusted certificate store. The certuser is optional for authority certificates.  If no certuser is specified, the certificate may not be used to authenticate a user.

2.    authority issued end-entity (e): Certificates of this type are not added to the trusted certificate store. The certuser is required for authority issued end-entity certificates.

3.    Self-signed identity certificate (s): Certificates of this type are not added to the trusted certificate store. The certuser is required for self-signed identity certificates.

 

--help

Displays the command help message.

--version

 

Displays the CIM Server version number.

EXIT STATUS

When an error occurs, an error message is written to stderr and an error value is returned. The following values are returned:

0

Success

1

General error

2

Connection failed

3

Connection timeout

4

Certificate already exists

5

Certificate does not exist

6

Invalid system user

EXAMPLES

Add the X509 self-signed identity certificate in the cert.pem file and associate it to certuser guest. This certificate will be added to the trusted certificate store:

cimtrust -a -U guest -f cert.pem –T s

Add the X509 authority root CA certificate in the ca.pem file with no certuser association. This certificate will be added to the trusted certificate store but may not be used to authenticate a user:

cimtrust -a -f ca.pem –T a

Add the X509 authority issued end-entity certificate in the user.pem file and associate it to certuser pegasus. This certificate may be used to authenticate user pegasus but will not be added to the trusted certificate store:

cimtrust -a -f user.pem –U pegasus –T e

Remove the certificate matching the specified issuer and serialnumber from the trust store:

cimtrust -r -i "/C=US/ST=California/L=Cupertino/O=Smart & Secure/OU=Secure Software Division/CN=dev.admin.ss.com" -n 01

Remove the certificate(s) matching the specified issuer and subject from the trust store:

cimtrust -r -i "/C=US/ST=California/L=Cupertino/O=Smart & Secure/OU=Secure Software Division/CN=dev.admin.ss.com" –S "/C=US/ST=California/L=Cupertino/O=Smart & Secure/OU=Secure Software Division/CN=dev.admin.ss.com”

List all the X509 certificates in the trust store:

cimtrust -l

SEE ALSO

cimcrl(1m), cimconfig(1m), cimserver(8)

cimcrl

NAME

cimcrl – add, remove or list  X509 Certificate Revocation Lists  in a PEM format CRL store.

SYNOPSIS

cimcrl -a -f file

cimcrl -r -i issuer

cimcrl -l [ -i issuer ]

cimcrl --help

cimcrl --version

Remarks

The cimcrl command requires that the CIM Server is running.  This command operates on a CRL store on the local system only.

DESCRIPTION

The cimcrl command provides a command line interface to manage X509 CRLs in the CRL store. The CRL store contains the CRLs used to revoke certificates in the CIM Server truststore. For more information on truststore operations see the cimtrust(1m)  command.

The add option of the cimcrl command adds the CRL from file to the CRL store. If a CRL for the specified issuer already exists in the CRL store, the CRL is replaced with the specified CRL.

The remove option of the cimcrl command removes the CRL for a specified issuer from the CRL store.

The list option of the cimcrl command lists the CRLs in the CRL store. The list can be filtered by specifying an issuer.

OPTIONS

cimcrl recognizes the following options:

-a

 

Adds the specified CRL to the CRL store. If the specified file contains an invalid CRL, an error message is returned and no action is taken. If the CRL for the specified issuer already exists in the CRL store, the CRL is replaced with the CRL specified in file.

-r

 

The remove option removes the CRL from the CRL store for a specified issuer.

-l

 

Displays the CRLs in the CRL store.

 

 

-f file

Specifies a PEM format file containing a CRL.

 

 

-i issuer

Specifies the issuer name for a CRL.

--help

 

Displays the command help message.

--version

 

Displays the CIM Server version number.

EXIT STATUS

When an error occurs, an error message is written to stderr and an error value is returned. The following values are returned:

0

Success

1

General error

2

Connection failed

3

Connection timeout

4

CRL does not exist

EXAMPLES

Add the CRL in class1crl.pem to the CRL store:

cimcrl -a -f class1crl.pem

List the CRL for a specified issuer:

cimcrl –l -i "/C=US/ST=California/L=Cupertino/O=Smart & Secure/OU=Secure Software Division/CN=dev.admin.ss.com"                                                                

Remove the CRL for a specified issuer:

cimcrl –r -i "/C=US/ST=California/L=Cupertino/O=Smart & Secure/OU=Secure Software Division/CN=dev.admin.ss.com"                                                        

SEE ALSO

cimtrust(1m), cimconfig(1m), cimserver(8)

Test Plan

Currently, the ssltrustmgr command is tested in the automated test suite. The test suite includes tests for both trust store and CRL management. It is proposed that the existing test suite be split into cimtrust and cimcrl command tests and the commands’ tests be enhanced to test the following:

Schedule

Action

Planned

Actual

Comment

PEP Submitted

5/15/06

5/12/06

 

PEP Reviewed

5/31/06

5/26/06

 

PEP Approved

6/16/06

6/02/06

Version 1.2

Code Committed

Pegasus 2.6

Pegasus 2.6 FC

Bugs 5327, 5350, 5472, 5634 and 5635

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.; EMC Corporation; Symantec Corporation; The Open Group.
Permission is hereby granted, free of charge, to any person obtaining a copy  of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: March 9th 2004 by Martin Kirk
Template version: 1.8