Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CSP(3)		      User Contributed Perl Documentation		CSP(3)

NAME
       CSP - A wrapper around OpenSSL for maintaining multiple Certificate
       Authorities.

SYNOPSIS
	 # csp help

DESCRIPTION
       CSP is a	perl module which uses openssl (openssl	version	0.9.6 or later
       is required).  Features include

       o   CSP leaves subject naming policy to the user. No checks are made on
	   the attribute names in the subject. This is good if you don't like
	   being asked a lot of	questions when issuing certificates.

       o   Configuration is reduced to specification of	extensions. This is
	   simplified using a simple CPP/MPP-type macro	interpreter in CSP.

       o   CSP is designed to easily handle multiple distinct Certificate
	   Authorities.	 Hence the name	which stands for Certificate Service
	   Provider.

       o   CSP can be used to produce a	web site (certificate repository, CRLs
	   etc etc) without the	need for cgi-scripts.

       o   CSP tries to	be as PKIX-compliant as	OpenSSL	allows.

CSP IN PRACTICE
       The typical application for CSP is a small CA (which may	or may not be
       part of a larger	pki) issuing mainly server and object signing
       certificates and	only few if any	user certificates. The distinction
       between user and	other certificates may seem arbitrary but experience
       shows that managing a large set of user certificates typically requires
       a more sofisticated system for managing and tracking requests.

       When setting up CSP for production use the author strongly recommends
       using a non network connected host for the CA operations. This computer
       will not	use much CPU or	disk resources and any old PC with Linux or
       *BSD should work	admirably. An old laptop might be a very good choice
       since it	can be locked away when	not in use. It might be	a good idea to
       equip the computer with a cd writer or some other means for making
       backups of the certificate directory.  Day to day operations include
       the following tasks.

       1.  Issuing certificates	based on pkcs10	or out-of-band (non pkcs10)
	   requests.

       2.  Backing up the csp main directory (see below) to read-only medium.

       3.  Producing the public	web site and exporting it (typically using
	   floppy or zip-drive)	to your	web server.

CONFIGURATION
       First set the environment variable OPENSSL to contain the absolute path
       of your OpenSSL binary. This is a requirement for everything that
       follows.	Next create a directory	where you will keep your CAs. This can
       be any directory	anywhere in your file system owned by anyone. A	sample
       directory "ca" in the distribution is included as a reference. A	good
       way to get started is to	copy this directory somewhere. Set $CSPHOME to
       point to	this directory.	The layout of this directory is	as follows:

	.
	|-- csp			 Certificate Authorities directory
	`-- etc
	    |--	aliases.txt	     Alternative names for DN attributes
	    |--	extensions.conf	     Default certificate extensions file
	    |--	crl_extensions.conf  Default crl extensions
	    |--	oids.conf	     Extra OIDs	(eg attribute types).
	    |--	public_html	     Default web site template files
	    `--	types.txt	     List of certificate types to support

       Most of these files are defaults	that are copied	to each	new CA when
       created.	This means that	if you need defaults used by all CAs you
       create you must make those edits	first of all.

       The oids.conf and aliases.txt should be edited to include support for
       any extra attribute types your CA systems must support. The format of
       these files should be obvious. The oids.conf includes support for the
       DC attribute.

       Next edit extensions.conf. This file is a default file which is copied
       to each new CA. Before you create your first CA edit this file to
       reflect extensions and defaults for all CAs created in this directory.
       The format of this file is explained in the EXTENSIONS section. Also
       edit the	crl_extensions.conf to include support for any crl extensions
       you might need. Remember	that after you create a	CA you must edit the
       local copy of these files to reflect the	requirements of	that
       particular CA.

       Finally edit the	files in public_html. The structure of this directory
       is explained in more detail in the section WEBSITE below.

       You are now ready to create your	first CA. If this is a self-signed CA
       creation	is done	in two steps: First create the directories and copy
       the configuration files.	The first argument "PCA" is a name of the CA
       in our example. Creation	of the CA "PCA"	is done	using the command "csp
       create".

	[leifj@njal CSP]$ ./csp	PCA create

       Next initialize "PCA". The last argument	is the distinguished name of
       the CA. CSP does	not impose any limit on	names which means that you can
       get away	with any DN as long as your oids.conf and aliases.txt include
       aliases and oids	for the	attribute types.

	[leifj@njal CSP]$ ./csp	PCA init --keysize=2048	\
			  --days=2190 'CN=CA,dc=example,dc=com'
	[CSP][PCA     ]	Generating CA key
	[CSP][PCA     ]	Private	key password: <...>
	[CSP][PCA     ]	Re-enter Private key password: <...>
	[CSP][PCA     ]	Successfully created CA	PCA

       List the	contents of this certificate provider:

	[leifj@njal CSP]$ ./csp	--list
	PCA

       Use openssl to dump the contents	of the CA certificate:

	[leifj@njal CSP]$ csp PCA dump

	... stuff deleted ...

       Now issue a new server certificate signed by PCA:

	[leifj@njal CSP]$ ./csp	PCA issue \
			    --keysize=1024 \
			    --noconfirm	\
			    'CN=www.example.com,dc=example,dc=com'
	[CSP][PCA     ]	Generating new key
	[CSP][PCA     ]	Private	key password: <...>
	[CSP][PCA     ]	Re-enter Private key password: <...>
	[CSP][PCA     ]	Create certificate request for CN=CA,dc=su,dc=se
	[CSP][PCA     ]	Signing	request

       Check the contents of PCA database (the --xinfo arg gives you the sha1
       and md5 fingerprints)

	[leifj@njal CSP]$ ./csp	PCA list --xinfo
	Serial	: 01
	Status	: Valid
	Subject	: CN=www.example.com,dc=example,dc=com
	Expires	: Wed Oct 10 10:28:32 2001
	SHA1	: A3:53:D7:DF:AE:A2:44:0A:0F:B8:29:31:E7:96:16:62:1F:52:DF:62
	MD5	: 04:2A:3A:1B:BB:B9:1E:08:4D:C3:14:CE:71:72:CC:86

       Finally generate	the public web site

	[leifj@njal CSP]$ mkdir	/tmp/export
	[leifj@njal CSP]$ ./csp	PCA genpublic --export=/tmp/export

       Now move	/tmp/export to a removable medium and transport	it to your web
       server.

EXTENSIONS
       Configuration of	extensions is done in the etc/<ca
       name>extensions.conf. The format	of this	file is	equivalent to the
       openssl extensions format. Read more about this in the openssl
       documentation.  This file also supports a simple	macro format similar
       to transarc mpp which in	turn is	essentially CPP	with '%' as the	magic
       character. The following	macros are supported:

	%ifdef/%endif
	%if/%endif
	%include

       The predicate in	the %if	macro can be almost any	perl expression	where
       macro %-expansion replaces perl variable	expansion.

WEB SITE
       The directory public_html in each CA directory contains template	files
       (MPP macro expansion is applied to these	files) for a public web	site.
       The included example has	the following organization

	 public_html
	 |-- certs
	 |   |-- cert.html.mpp
	 |   |-- expired.html.mpp
	 |   |-- index.html.mpp
	 |   |-- revoked.html.mpp
	 |   |-- valid.html.mpp
	 `-- index.html.mpp

       The csp command "csp genpublic" will produce a directory	in the export
       directory (specified by --export) which looks like this:

	 <export>
	 |-- ca.crt
	 |-- certs
	 |   |-- 01.crt
	 |   |-- 01.html
	 |   |-- 01.pem
	 |   |-- expired.html
	 |   |-- index.html
	 |   |-- revoked.html
	 |   `-- valid.html
	 |-- crl-v1.crl
	 |-- crl-v2.crl
	 `-- index.html

       The ca.crt, crl-v1.crl and crl-v2.crl are copies	of the corresponding
       files from the master repository. Each certificate in the repository is
       stored in <export>/certs	as DER,	PEM and	as an HTML page	derived	from
       public_html/certs/cert.html.mpp by macro	expansion. All other pages are
       simply produced by macro	expansion of the corresponding .mpp-files and
       apart from certs/cert.html.mpp none of these files need exist or	have
       the names they have in the example above.

       When performing macro expansion on public_html/certs/cert.html.mpp the
       following variables are available:

	 DATE		   The date (using localtime(time)) of
			   the export operation.
	 SUBJECT_SERIAL	   The serial number of	the certificate.
	 SUBJECT_DN	   The distinguished name (DN) of the
			   certificate.
	 ISSUER_DN	   The distinguished name (DN) of the
			   CA certificate.
	 SUBJECT_SHA1	   The SHA1-fingerprint	of the
			   certificate.
	 SUBJECT_MD5	   The MD5-fingerprint of the
			   certificate.
	 SUBJECT_NOTBEFORE The date when this certificate
			   becomes valid.
	 SUBJECT_NOTAFTER  The date when this certificate
			   expires.

       When all	other files in the directories (public_html and
       public_html/certs) are run through the macro preprocessor to produce
       HTML files the following	variables are available:

	 DATE		    The	date (using localtime(time)) of
			    the	export operation.
	 VALID		    An HTML table of valid certificates.
	 VALID_COUNT	    The	number of valid	certificates.
	 REVOKED	    An HTML table of revoked certificates.
	 REVOKED_COUNT	    The	number of revoked certificates.
	 EXPIRED	    An HTML table of expired certificates.
	 EXPIRED_COUNT	    The	number of expired certificates.
	 SUBJECT_SERIAL	    The	serial number of the CA	certificate.
	 SUBJECT_NOTAFTER   The	date when the CA certificate
			    expires.
	 SUBJECT_NOTBEFORE  The	date when the CA certificate
			    became valid.
	 SUBJECT_DN	    The	distinguished name (DN)	of the
			    CA certificate.
	 SUBJECT_MD5	    The	MD5-fingerprint	of the CA
			    certificate.
	 SUBJECT_SHA1	    The	SHA1-fingerprint of the	CA
			    certificate.

AUTHOR
       Leif Johansson <leifj@it.su.se> Stockholm University

ACKNOWLEDGEMENTS
       The web site generation was inspired by work by Heinar Hillbom
       <Einar.Hillbom@umdac.umu.se> UMDAC, UmeAY Universitet

SEE ALSO
       perl(1),	openssl(1).

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1800:
	   Non-ASCII character seen before =encoding in	'UmeAY'. Assuming
	   CP1252

perl v5.24.1			  2007-03-10				CSP(3)

NAME | SYNOPSIS | DESCRIPTION | CSP IN PRACTICE | CONFIGURATION | EXTENSIONS | WEB SITE | AUTHOR | ACKNOWLEDGEMENTS | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CSP&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help