Skip to content

Commit

Permalink
Clarify documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@gotthardp
gotthardp committed Jan 16, 2021
1 parent 7855dbe commit 24adf37
Show file tree
Hide file tree
Showing 5 changed files with 49 additions and 69 deletions.
63 changes: 36 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ $ autoreconf
Set PKG_CONFIG_PATH and then the usual will work:
```cmd
$ export PKG_CONFIG_PATH="/usr/local/opt/[email protected]/lib/pkgconfig"
$ ./Configure
$ ./configure
$ make
$ make install
```
Expand Down Expand Up @@ -174,7 +174,7 @@ General OPTIONS

OPTIONS for OPERATION getca are
-i <string> CA identifier string
-F <name> Fingerprint algorithm (md5|sha1)
-F <name> Fingerprint algorithm (md5|sha1|sha224|sha256|sha384|sha512)

OPTIONS for OPERATION enroll are
-k <file> Private key file
Expand All @@ -201,36 +201,41 @@ OPTIONS for OPERATION getcrl are
-w <file> Write CRL in file
```
SSCEP also supports configuration via a configuration file (-f).
SSCEP also supports configuration via a configuration file (`-f`).
This is the recommended way to configure SSCEP and all the examples
in below assume that you have done so.
All configuration options are key-value pairs separated with one
or more space characters:
All configuration options are key-value pairs separated with the equal sign
and grouped into sections:
"Key" [spaces] "Value"
```
[section]
Key = Value
```
Quotation marks are optional - they are needed only if the value contains
space characters (space or tab). Quotation marks inside the value string
must be escaped using a backslash:
"Key" [spaces] "Value \"containing quotation marks\""
```
Key = "Value \"containing quotation marks\""
```
Comment lines (lines starting with '#') and empty lines are discarded.
Here are the available configuration file keys and example values:
| Key | Explanation | Example | Command options |
|-------|-------------------|---------|---------|
| URL | URL of the SCEP server. | `http://localhost/cgi-bin/pkiclient.exe` | `-u` |
| URL | URL of the SCEP server. | `http://example.com/scep` | `-u` |
| CACertFile | Sigle CA certificate file, or mutiple CA certificates suffixed with `-0`, `-1`, ... to write (getca) or to choose from (all other operations). | `./ca.crt` |`-c` |
| CAIdentifier | Some CAs require you to define this. | `mydomain.com` | `-i` |
| CertReqFile | Certificate request file created with mkrequest. | `./local.csr` | `-r`
| EncAlgorithm | PKCS#7 encryption algorithm. Available algorithms are des, 3des, blowfish, aes/aes128, aes192 and aes256. NOTE: SCEP provides no mechanism to "negotiate" the algorithm - even if you send 3des, reply might be des (same thing applies to SigAlgorithm). | | `-E` |
| EncCertFile | If your CA/RA uses a different certificate for encyption and signing, define this. CACertFile is used for verifying the signature. | `./enc.crt` | `-e` |
| SignCertFile | Instead of creating a self-signed certificate from the new key pair use an already existing certficate/key to sign the SCEP request. If the "old" certificate and key is used, the CA can verify that the holder of the private key for an existing certificate re-enrolls for a renewal certificate, allowing for automatic approval of the request. Requires specification of the corresponding signature private key file (-K, SignKeyFile). | `./sig.crt` | `-O` |
| SignCertFile | Instead of creating a self-signed certificate from the new key pair use an already existing certficate/key to sign the SCEP request. If the "old" certificate and key is used, the CA can verify that the holder of the private key for an existing certificate re-enrolls for a renewal certificate, allowing for automatic approval of the request. Requires specification of the corresponding SignKeyFile (`-K`). | `./sig.crt` | `-O` |
| SignKeyFile | See SignCertFile. Specifies the corresponding private key. | `./sig.key` | `-K` |
| FingerPrint | Display fingerprint algorithm. Available algorithms are md5 and sha1. Default is md5. || `-F` |
| FingerPrint | Display fingerprint algorithm. Available algorithms are md5, sha1, sha224, sha256, sha384 and sha512. Default is md5. || `-F` |
| GetCertFile | Write certificate asquired via getcert operation. | `./cert.crt` | `-w` |
| GetCertSerial | Certificate serial number. Define this for getcert. The value is defined as a decimal number. | `12` | `-s` |
| GetCrlFile | Write CRL to file. | `./crl.crl` | `-w` |
Expand Down Expand Up @@ -294,8 +299,12 @@ commonName = device
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names
certTemplateName = ASN1:UTF8String:pc-client
[ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
```
To create a key and a request named local.key and local.csr run:
Expand Down Expand Up @@ -347,7 +356,7 @@ $ openssl x509 -in ca.crt -noout -fingerprint
```
If the CA sends a certificate chain, sscep writes all certificates in the
order it founds them in reply and names them with an integer prefix
order it founds them in reply and names them with an integer suffix
(-number) appended to CACertFile.
```bash
Expand All @@ -374,15 +383,16 @@ certificate to use as `-c` and (optionally) `-e` in subsequent operations.
Some CAs may give you a three (or more) certificates, the root CA(s) plus
different RA certificates for encryption and signing. If that's your case,
you have to define encryption certificate with command line option (-e).
you have to define encryption certificate with command line option (`-e`).
Probably it is the certificate with key usage "Key Encipherment".
You may also use the base name (e.g. ca.crt) of all certificates and
rely on an automated certificate selection. The system:
You may also use the base name (e.g. `ca.crt`) of all certificates and
rely on an automated certificate selection. The system loads all available
certificates (`ca.crt-0`, `ca.crt-1`, ...) and then:
1. Tries to find a certificate that:
* Is at the end of the received chain, i.e. do not sign other certificate.
* Has key usage "Digital Signature" (for -c) or "Key Encipherment"
(for -e), or does not have any key usage defined.
* Has key usage "Digital Signature" (for `-c`) or "Key Encipherment"
(for `-e`), or does not have any key usage defined.
2. If no such key is found, selects the first certificate in the chain, which
is usually the right certificate anyway.
Expand All @@ -401,14 +411,14 @@ with. Keep this in mind when installing the CA cert in /etc/isakmpd/ca.
### STEP 4 - Make enrollment
You need to supply URL (-u), CACertFile (-c), PrivateKeyFile (-k),
CertReqFile (-r) and output LocalCertFile (-l). PrivateKeyFile is the key
You need to supply URL (`-u`), CACertFile (`-c`), PrivateKeyFile (`-k`),
CertReqFile (`-r`) and output LocalCertFile (`-l`). PrivateKeyFile is the key
generated in step 2 (local.key), CertReqFile is the request (local.csr)
and LocalCertFile is where the enrolled certificate will be written once ready.
If your CA/RA have different certificates for encryption and signing, and you
do not want to use the auto-selection mechanism, you must provide also the
encryption certificate EncCertFile (-e).
encryption certificate EncCertFile (`-e`).
Normally, the enrollment looks like this:
Expand All @@ -434,10 +444,9 @@ First message sent is PKCSReq, that's where your request goes. Then the CA
writes request down and sends reply PENDING, indicating that the certificate
is not signed yet. SSCEP polls periodically for the certificate by sending
GetCertInitial messages until the CA returns SUCCESS. The polling interval
can be adjusted with PollInterval, or command line option (-t). You can
interrupt the process any time and start again using "sscep enroll ..".
You should use the command line option (-R) when you continue the interrupted
enrollment.
can be adjusted with PollInterval (`-t`). You can interrupt the process any
time and start again using "sscep enroll ..". You should use the command line
option (`-R`) when you continue (resume) the interrupted enrollment.
If the CA is configured for automatic enrollment (and your request includes
the challenge password), it returns SUCCESS as a first reply. Otherwise, the
Expand All @@ -453,7 +462,7 @@ a self-signed certificate created from the new key pair).
If you want to renew the certificate created previously (local.crt), you
follow the enrollment procedure as described before, but supply the current
(old) key and certificate as SignKeyFile (-K) and SignCertFile (-O).
(old) key and certificate as SignKeyFile (`-K`) and SignCertFile (`-O`).
```bash
$ ./sscep enroll -u http://example.com/scep -c ca.crt -K local.key -O local.crt \
Expand All @@ -479,7 +488,7 @@ Certificate /etc/isakmpd/certs/local.crt
CA certificate /etc/isakmpd/ca/ca.crt
And pay attention to CA certificate if your enrollment was done via RA
server. "openssl verify -CAfile ca.crt local.crt" is your friend here.
server. `openssl verify -CAfile ca.crt local.crt` is your friend here.
Expand All @@ -499,7 +508,7 @@ $ ./sscep getcrl -f sscep.conf
I'd like to thank the following people for providing me feedback:
Fiel Cabral
Fiel Cabral,
Manuel Gil Perez
Expand Down
36 changes: 0 additions & 36 deletions README.packaging
View file

This file was deleted.

7 changes: 7 additions & 0 deletions README.install → doc/README.AIX
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,10 @@ Path: /usr/lib/objrepos
CertNanny.sscep a.b.c.d COMMITTED Simple SCEP client
#

To create a package the mkinstallp is used. This command is
part of the fileset bos.adt.insttools which is not installed
by default. You need to install this package to generate lpp
packages

Furthermore, to run mkinstallp (and therefore "make package")
you need to be root or a member of the system group.
4 changes: 2 additions & 2 deletions src/sscep.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1255,10 +1255,10 @@ usage() {
" -d Debug output (more verbose, for debugging the implementation)\n"
"\nOPTIONS for OPERATION getca are\n"
" -i <string> CA identifier string\n"
" -F <name> Fingerprint algorithm\n"
" -F <name> Fingerprint algorithm (md5|sha1|sha224|sha256|sha384|sha512)\n"
"\nOPTIONS for OPERATION getnextca are\n"
" -C <file> Local certificate chain file for signature verification in PEM format \n"
" -F <name> Fingerprint algorithm\n"
" -F <name> Fingerprint algorithm (md5|sha1|sha224|sha256|sha384|sha512)\n"
" -c <file> CA certificate file (write if OPERATION is getca or getnextca)\n"
" -w <file> Write signer certificate in file (optional) \n"
"\nOPTIONS for OPERATION enroll are\n"
Expand Down
8 changes: 4 additions & 4 deletions sscep.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,13 @@ URL = http://localhost/scep
# CA certificate file (write if OPERATION is getca)
# CACertFile = ca.crt

# PKCS#7 encryption algorithm (des|3des|blowfish)
# PKCS#7 encryption algorithm (des|3des|blowfish|aes[128]|aes192|aes256)
# EncAlgorithm = 3des

# PKCS#7 signature algorithm (md5|sha1)
# PKCS#7 signature algorithm (md5|sha1|sha224|sha256|sha384|sha512)
# SigAlgorithm = sha1

# Note: this could be very misleading, current SCEP draft provides no
# Note: this could be very misleading, the SCEP standard provides no
# mechanism to "negotiate" the algorithm - even if you send 3des, reply
# might be des.

Expand Down Expand Up @@ -124,7 +124,7 @@ storelocation = LOCAL_MACHINE
# CA identifier string, required by some CA
# CAIdentifier = "CA Identifier"

# Fingerprint algorithm (md5/sha1)
# Fingerprint algorithm (md5|sha1|sha224|sha256|sha384|sha512)
# FingerPrint = md5


Expand Down

0 comments on commit 24adf37

Please sign in to comment.