AutoSScep 1.0 - Configuration file manual page

A...............Configuration file syntax
B...............Configuration file structure
B.1.............General Options
B.2.............Certification Authority(s) data
B.3.............Certificate(s) data
B.3.1...........X.509v3 Extensions
B.3.2...........Value for X.509v3 Extensions
C...............Summary of main commands
D...............Default Values
E...............Configuration example

A. Configuration file syntax
	A command has the following structure
		commandname = "value"
	The value MUST be written between "" quotation marks  !!
	Only one command for line is allowed.
	Spaces are allowed after and before
	The # (sharp) indicates a comment line.
	Commands for Certification Authority ([CA] [/CA]), certificate ([Certificate] [/Certificate]) data
	and X.509v3 Extension session must be placed at the beginning of the line.
	A value must be on the same line of its command.
	Unrecognized commands are signaled in execution, but ignored.

B. Configuration file structure
	There are three main parts:

		1. General Option :
			all that concerns file locations and program executions
		2. Certification Authority(s) data
		3. Certificate(s) data



B.1. General Options
	Requested values
	- CA directory and/or prefix of CA certificates
		CADir = "[]"
	- Certificate directory and/or prefix of certificates file
		CertDir = "[value]"
	- Private keys directory and/or prefix
		KeyDir = "[value]

	n.b. It's advisable to insert absolute paths

	Optionally you can indicate
	- number of days (before that the certificates expire) to start enrollment (default is 7)
		DaysBeforeExpire = "[value]"
	- number of bits for private keys (default = 1024)
	- signature algorithm  (md5 o sha1)
		SigAlgo = "[value]"
	- executions modes ( values : yes or no )
		- Verbose = "[value]"
			Shows details about execution
		- Debug = "[value]"
			Shows all the encrypted messages
	- An extracommand to be executed at the end if some certificate was enrolled
		ECommand = "[command]"

	N.B. General options must be placed before CAs and Certificates data !!!


B.2. Certification Authority(s) data
	This part of file starts with
	[CA] and ends with [/CA] (these keywords must be placed at the beginning of line).
	
	Required values
	- Distinguished Name
		DN = "[value]"
	- Complete cgi scep url ( http://<host-name>[:<port-num>]/<path> ... )
		URL = "[value]"
		if not specified the port-num is setted to 80
	- CA certificate file name (for the sign check)
		CertFile = "[value]"
	- CA certificate file name used for encryption (in some cases it's the same CA certificate)
		EncCertFile = "[value]"

	Optionally values
	- CA encryption algorithm
		EncAlgo = "[value]"
		(des, blowfish e 3des (default des))
	- Virtual-host hosting for the scep server (yes or no)
		VHost ="[value]"
	n.b. if any doubts yes value should be right 

B.3. Certificate(s) data
	This part starts with [Certificate] and ends with [/Certificate] (these keywords must be placed at the beginning of line).

	Required values
	- Certificate file name (also used as identifier)
		CertFile = "[value]"
	- Key file name
		KeyFile = "[value]"
	n.b. the name is relative to the paths specified in the general options

	- The DN (Distinguished name) of issuer CA (only an identifier)
		CADN = "[value]"
	- DN data for the certificate
		Email = "[value]"
		Country = "[value]"  (the short identifier US, UK , IT etc...)
		State = "[value]"
		Location = "[value]"
		Organization = "[value]"
		OrgUnit = "[value]"
		CommonName = "[value]"
	(OrgUnit and Email are optional for AutoSscep)
	
	Optional values
	- Request command : an external command executed for new pending requests on CA.
	This option can be used to advice the CA administrator about your request for example
	with a sender mail script.
		ReqCommand = "[value]"
	(This command is executed only for the NEW pending requests and is otherwise ignored.)
	- Challenge Password: this parameter in a cert request allow the automatic authentication for the request
	using a pre-shared secret (it is also used for certificate revocation) . 
		ChallengePassword="[valore]"

B.3.1 X.509v3 Extensions
	Optionally it is possible to specify some X.509v3 Extension for the certificate requests.
	The extensions list start with [X509v3EXT] and ends with [/X509v3EXT] (these keywords must be placed at the beginning of line).

	AutoSscep allows to insert only a few of all the extensions specified in RFC2459 and included in Openssl libraries.
	- Key Usage
	- Subject Alternative Name
	- Basic Constraint
	- Extended Key Usage
	- Netscape Comment
	- Netscape Certificate Type

B.3.2 Value for X.509v3 Extensions

	If the extension is critical it must be indicated at the beginning of value followed from a comma
				Ex: key_usage = "critical, digitalSignature"
	More values for the same extension is indicated as a comma separated list
				Ex: key_usage = "digitalSignature,nonRepudiation"

	- Netscape Comment
		command: netscape_comment
		value: a string

	- Subject Alternative Name
		command: subject_alt_name
		value: a string

 	- Basic Constraint
		command: basic_constraints
		value:
		request for a ca certificate  ------ CA:true
		request for another entity of PKI ----- CA:false

	- Key Usage (comma list)
		command: key_usage
		values:
		USAGE ---- KEYWORD
		Digital Signature ---- digitalSignature
		Non Repudiation ---- nonRepudiation
		Key Encipherment ---- keyEncipherment
		Data Encipherment ---- dataEncipherment
		Key Agreement ---- keyAgreement
		Certificate Sign ---- keyCertSign
		CRL Sign ---- cRLSign
		Encipher Only ---- encipherOnly
		Decipher Only ----decipherOnly

	- Extended Key Usage
		command: extended_key_usage
		values:
		KEYWORD ---- EXTENDED KEY USAGE
		serverAuth ---- TLS Web Server Authentication
		clientAuth ---- TLS Web Client Authentication
		codeSigning ---- Code Signing
		emailProtection ---- E-mail Protection
		timeStamping ---- Time Stamping
		msCodeInd ---- Microsoft Individual Code Signing
		msCodeCom ---- Microsoft Commercial Code Signing
		msCTLSign ---- Microsoft Trust List Signing
		msSGC ---- Microsoft Server Gated Crypto
		msEFS ---- Microsoft Encrypted File System
		nsSGC ---- Netscape Server Gated Crypto

	- Netscape Certificate Type
		command: netscape_cert_type
		values:
		NS CERTIFICATE TYPER ---- KEYWORD
		SSL Client ---- client
		SSL Server ---- server
		S/MIME ---- email
		Object Signing ---- objsign
		Unused ---- reserved
		SSL CA ---- sslCA
		S/MIME CA ---- emailCA
		Object Signing CA ---- objCA

C. Summary of main commands

D. Default values
	If not specified the following values are so setted 
		DaysBeforeExpire = "7"
		Verbose = "no"
		Debug = "no"
		KeyBits = "1024"
		SigAlgo = "md5"
	For the CA
		EncAlgo = "des"
		VHost = "no"

E. Configuration example

--------------Example------------------------------------------------------------------------------------------------
# Config file for autoScep

### General option

# The directory that contains certificates
CertDir = "/home/cert/"

# The directory that contains the private keys
KeyDir = "/home/keys/"

# The number of expiration days before start enroll
DaysBeforeExpire = "2"

# The directory that contains the CA's certificates
CADir = "/home/racerts/"

### Info e debug option
# Possible values: yes or no.
Verbose = "yes"
Debug = "no"

# The bits for the modules of private keys
KeyBits = "2048"

# Signature algorithm (md5 or sha1)
SigAlgo = "md5"

### CAs' data
# Define the CAs data

[CA]
DN = "C=IT, O=CA Organization, OU=Certification Authority, CN=myCA/Email=info@myCAdomain"
URL = "http://<ca- host>/cgi-bin/scep/scep"
CertFile = "ca.crt-0"
EncCertFile = "ca.crt-0"
# Encryption algorithm: des, 3des or blowfish. Default: des
EncAlgo = "des"
VHost = "yes"
[/CA]

[Certificate]
CertFile = "mycertificate.crt"
KeyFile = "mykey.key"

# cert's CA Data
    CADN = "C=IT, O=CA Organization, OU=Certification Authority, CN=myCA/Email=info@myCAdomain"

# DN Data
Email = "mymail@mydomain"
Country = "IT"
State = "BS"
Location = "Brescia"
Organization = "My Organization"
OrgUnit = "my unit"
CommonName = "me"

[X509v3EXT]
key_usage = "digitalSignature,keyEncipherment,nonRepudiation"
subject_alt_name =  "mymail@mydomain"
basic_constraints = "critical,CA:false"
netscape_cert_type = "client,server"
extended_key_usage = "serverAuth,clientAuth,codeSigning,emailProtection,timeStamping,msCodeInd,msCodeCom"
netscape_comment = "VPN point to point"
[/X509v3EXT]

[/Certificate]


--------------End-of-Example-------------------------------------------------------------------------------------------------