Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
tutorial:adm:caw_driver [2018/10/22 08:02] fiserp [The CAW driver] |
tutorial:adm:caw_driver [2019/11/19 13:08] fiserp [Installation] |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ===== The CAW driver ===== | ||
+ | The CAW driver is our native certificate authority driver. In essence, it is a shell script encompassing ordinary OpenSSL certificate authority. This has many pros: | ||
+ | * If you can do it in openssl.cnf, | ||
+ | * Supported on any Linux/UNIX platform which has openssl, bash and coreutils. Also supported on MinGW. | ||
+ | * Readable script that is easy to debug and fix. Anyone can do it. | ||
+ | * You can migrate almost any existing CA into the CAW. | ||
+ | * Migrate certificates, | ||
+ | * Construct openssl certificate db (plain text file of given format). If you have the data, this can be done with a few hours of scripting. | ||
+ | * Native support for PKCS#11 crypto tokens. | ||
+ | * Also, we give out almost totally preconfigured CAW instance and installation instructions. | ||
+ | * Also, the deployment is simply unpacking CAW into a folder. Need another CA instance? Unpack CAW into another folder. | ||
+ | It also has some cons: | ||
+ | * There are plenty of bad openssl.cnf tutorials on the internet. Seriously. We are fighting it by heavily commenting the CAW-supplied configuration but that is basically all we can do about it. :-/ | ||
+ | * OpenSSL integration with PKCS#11 tokens is not something that "just works" | ||
+ | * The CA is not concurrent. The CAW handles it by pessimistic locking. | ||
+ | |||
+ | ==== The CAW script ==== | ||
+ | CAW is a shell wrapper above the OpenSSL-based certificate authority (abbreviated: | ||
+ | CAW is primarily created as a CA backend for the CzechIdM Certificate Authority module but it is possible to extend/ | ||
+ | |||
+ | For the list of capabilities and input/ | ||
+ | < | ||
+ | ./caw | ||
+ | Unknown command '' | ||
+ | Usage: ./caw command [--param1 value1 --param2 value2 ...] | ||
+ | ... | ||
+ | COMMAND create-key-and-cert - generates new private key, CSR and signs a certificate | ||
+ | OUTPUT | ||
+ | Success: Serial number of the issued certificate written onto STDOUT. Return code 0. | ||
+ | Error: Error message on STDERR. Return code 1. | ||
+ | PARAMETERS | ||
+ | --country | ||
+ | --state | ||
+ | --locality | ||
+ | --org organizationName. Mandatory. | ||
+ | --ou | ||
+ | --cn | ||
+ | --mail | ||
+ | --pass | ||
+ | ... and so on ... | ||
+ | </ | ||
+ | |||
+ | In its core, CAW uses a well-known OSSL CA all with its '' | ||
+ | |||
+ | **But beware**, CAW has also its own configuration file '' | ||
+ | |||
+ | Additional information can be found in one of those three places: | ||
+ | * In the CAW usage page. Simply invoke '' | ||
+ | * As a comment in the '' | ||
+ | * As a comment in the CAW script itself (i. e. **authors**, | ||
+ | ==== Core functions ==== | ||
+ | * Self-contained CA | ||
+ | * CAW does not depend on the global ''/ | ||
+ | * You can run different CAs just by giving each its own folder. | ||
+ | * Installation is merely unpacking a tarball and generating CA certificate and starting serial number. | ||
+ | * Handling concurrency problems | ||
+ | * OpenSSL CA ('' | ||
+ | * Private key and CSR private storage | ||
+ | * CAW archives all files it has created, including users' private keys and CSRs. Private keys all always AES-encrypted by a password which the end-user specifies. Therefore even the CA does not have an access to the private key. | ||
+ | * Support for hardware tokens using PKCS11 | ||
+ | * If your OpenSSL version can support your hardware token, you can use it in CAW. Only thing you need to do is to configure it in '' | ||
+ | * Unix-like style of invocation | ||
+ | * Everything that goes into the CAW is a **command line argument**. Everything that goes out of the CAW is either a output of successful operation (on '' | ||
+ | * Return code for successful operation is '' | ||
+ | * All information going to/from CAW is in **printable form**, large data mainly as PEM or base64-encoded. | ||
+ | * Usable as a root or intermediary CA | ||
+ | * CAW allows additional certificates to be added to the chain when downloading a particular cetificate. This can be used to supply all parts of the certificate chain from the issuing CA to the root CA. If no such additional certificates are specified, CAW acts as a root CA. | ||
+ | * Private key and certificate creation | ||
+ | * When user supplies just the **SubjectDN components**, | ||
+ | * CSR signing | ||
+ | * User-provided CSR is checked for sufficient **signature algorithm** and for **SubjectDN components**. CAW makes sure the comparison is text-based (by regexes) and does not care about datatypes. This effectively solves usability problems with OpenSSL' | ||
+ | * Certificate prolongation | ||
+ | * Because CAW stores CSRs, it is possible to prolong certificate by reissuing it with new validity period. All that is needed is certificate' | ||
+ | * CAW will not allow the expired/ | ||
+ | * This is not a big security risk because for access the CSRs, an attacker must have access to the machine running the CA. If he does, you have much bigger problem than some accessible CSR. | ||
+ | * Certificate revocation | ||
+ | * Revoke certificate just by specifying its serial number and revocation reason. | ||
+ | * Certificate database querying | ||
+ | * CAW provides basic interface to query certificate database and for certificate validation. | ||
+ | * Certificate bundling | ||
+ | * When the issued certificate is requested for download, user can specify if he wants it to be bundled with private key and/or whole certificate chain. | ||
+ | * When requesting the bundle with private key, user must specify the password he has given during the certificate creation. | ||
+ | * CRL issuing and publishing | ||
+ | * CAW enables you to create CRLs just by calling '' | ||
+ | * Housekeeping tasks | ||
+ | * CAW takes care of orphan files and similar things that can happen during the life of CA. All those tasks are done by '' | ||
+ | |||
+ | ==== Installation ==== | ||
+ | - Create separate user for your authority. **Ensure that no other user can read the home directory.** This happens for example on the (open)SuSE where each home is granted to the '' | ||
+ | [root@ca ~]# useradd -r -m -s /bin/bash authority1 | ||
+ | </ | ||
+ | - Move the CAW directory to the user's home.< | ||
+ | [root@ca ~]# mv caw.tgz / | ||
+ | [root@ca authority1]# | ||
+ | [root@ca authority1]# | ||
+ | total 28 | ||
+ | drwxr-xr-x 4 1000 users 4096 Aug 24 14:36 caw | ||
+ | -rw-r--r-- 1 root root 24563 Aug 24 15:16 caw.tgz | ||
+ | [root@ca authority1]# | ||
+ | [root@ca authority1]# | ||
+ | </ | ||
+ | - Ensure that '' | ||
+ | [root@ca authority1]# | ||
+ | [root@ca caw]# chmod 750 caw | ||
+ | </ | ||
+ | - Create new starting serial number. This number can be, say, '' | ||
+ | [root@ca caw]# cd ca/ | ||
+ | [root@ca ca]# openssl rand -hex 16 > serial | ||
+ | </ | ||
+ | - **If you want** to use serial number prefixes, now it is the time to set it up. **If you don't know what it is, you can safely skip this step.** Suppose the random serial was '' | ||
+ | - Generate your CA certificate the usual way. For how to set it up with PKCS11 crypto token, see the end of this document. **Select the appropriate private key size.** Also, there are x509v3 certificate extensions which are handy to have in the authority' | ||
+ | [root@ca ca]# su - authority1 | ||
+ | [authority1@ca ~]$ cd caw/ca/ | ||
+ | [authority1@ca ca]$ pwd | ||
+ | / | ||
+ | [authority1@ca ca]$ openssl genrsa -out private/ | ||
+ | [authority1@ca ca]$ chmod 400 private/ | ||
+ | [authority1@ca ca]$ openssl req -new -in private/ | ||
+ | [authority1@ca ca]$ openssl x509 -req -in ca.csr -signkey private/ | ||
+ | [authority1@ca ca]$ rm ca.csr | ||
+ | </ | ||
+ | - CAW folder comes with a number of empty directories. Although needless now, they are automatically used by the '' | ||
+ | - Check the '' | ||
+ | - Enable (configure) the PKCS11 engine or disable it entirely (comment it out). | ||
+ | - Configure '' | ||
+ | - Configure parameters in the '' | ||
+ | - Configure certificate extensions in the '' | ||
+ | - Check the '' | ||
+ | - Configure '' | ||
+ | - Configure the '' | ||
+ | - Configure the '' | ||
+ | - **If you do not use PKCS11 crypto token (that is, you want to use '' | ||
+ | - Generate the empty CRL file.< | ||
+ | [authority1@ca caw]$ ./caw create-crl | ||
+ | </ | ||
+ | - You should be good to go. Follow the examples and try to obtain your first certificate. | ||
+ | |||
+ | ==== Examples ==== | ||
+ | - Create private key and certificate< | ||
+ | [root@ca ~]# ./caw create-key-and-cert --country CZ --state "Czech Republic" | ||
+ | 0C0774BACDF2CA2A52BEEF68A0F1D411 | ||
+ | </ | ||
+ | - Prolong certificate< | ||
+ | [root@ca ~]# ./caw prolong-cert --serial 0C0774BACDF2CA2A52BEEF68A0F1D411 | ||
+ | 0C0774BACDF2CA2A52BEEF68A0F1D412 | ||
+ | </ | ||
+ | - Download (private key, | ||
+ | [root@ca ~]# ./caw get-cert --serial 0C0774BACDF2CA2A52BEEF68A0F1D411 --with-pkey --pass demodemo --with-chain | ||
+ | MIIKoQIBAzCCCmcGCSqGSIb3DQEHAaCCClgEggpUMIIKUDCCBQcGCSqGSIb3DQEHBqCCBPgwggT0 | ||
+ | ... | ||
+ | FbAM6nS5jJYQ4s4VKDElMCMGCSqGSIb3DQEJFTEWBBRGj5/ | ||
+ | CQYFKw4DAhoFAAQUCqImx0Un2qmtSACpEWD4i2ivunMECFJnEuzDIEtHAgIIAA== | ||
+ | </ | ||
+ | - Revoke a certificate< | ||
+ | [root@ca ~]# ./caw revoke-cert --serial 0C0774BACDF2CA2A52BEEF68A0F1D411 --reason keyCompromise | ||
+ | </ | ||
+ | - Refresh the CRL< | ||
+ | [root@ca ~]# ./caw create-crl | ||
+ | </ | ||
+ | |||
+ | ==== Deconfiguring default PKCS11 engine ==== | ||
+ | By default, CAW comes with a preconfigured template for the PKCS11-enabled crypto engine. In some deployments, | ||
+ | This short howto will show you how to swap preconfigured PKCS11 engine for the more usual setup. | ||
+ | |||
+ | The '' | ||
+ | |||
+ | To deconfigure the PKCS11 template: | ||
+ | - Edit the '' | ||
+ | - Comment out '' | ||
+ | - Comment out whole '' | ||
+ | - Comment out whole '' | ||
+ | - Comment out whole '' | ||
+ | - In the '' | ||
+ | - Edit the '' | ||
+ | - Set the '' | ||
+ | ==== Configuring CAW with the PKCS11 crypto token ==== | ||
+ | <note warning> | ||
+ | **DISCLAIMER: | ||
+ | * Use real hardware crypto token. | ||
+ | * Generate CA private key directly on the token (via openssl, p11-tool or such). | ||
+ | * The private key pin (and security pin) really should not be 1234 (or 123456 respectively). Use reasonably strong pins. | ||
+ | |||
+ | **If you modify the example below according to those remarks, then your setup should be secure enough.** | ||
+ | </ | ||
+ | - First, we generate the CA private key. This is not secure, but it is quicker for demonstration purposes. For more info, see the disclaimer.< | ||
+ | [root@ca ~]# openssl genrsa -out ca.key 4096 | ||
+ | </ | ||
+ | - Create the CA CSR.< | ||
+ | [root@ca ~]# openssl req -new -key ca.key -out ca.csr -sha512 | ||
+ | </ | ||
+ | - Create the CA certificate with appropriate extensions.< | ||
+ | [root@ca ~]# openssl x509 -req -days 3650 -in ca.csr -signkey ca.key -out ca.crt -sha512 -extfile ca_extensions.txt | ||
+ | </ | ||
+ | - SoftHSM needs the key to be in PKCS8 format. The default generated from OpenSSL is PKCS5 so we have to convert it. Also, using '' | ||
+ | [root@ca ~]# openssl pkcs8 -in ca.key -topk8 -out ca_pk8.key -nocrypt | ||
+ | </ | ||
+ | - Suppose the SoftHSM is installed and configured. The SoftHSM' | ||
+ | [root@ca ~]# softhsm2-util --init-token --slot 0 --label ca --so-pin 123456 --pin 1234 | ||
+ | The token has been initialized. | ||
+ | [root@ca ~]# softhsm2-util --pin 1234 --so-pin 123456 --import ca_pk8.key --label ca --id A1B2 --no-public-key --slot 0 | ||
+ | The key pair has been imported. | ||
+ | </ | ||
+ | - We have to link our token with openssl and test the setup. If everything goes right, we get the output similar to this one:< | ||
+ | [root@ca ~]# openssl engine -t dynamic -pre SO_PATH:/ | ||
+ | (dynamic) Dynamic engine loading support | ||
+ | Success: SO_PATH:/ | ||
+ | Success: ID:pkcs11 | ||
+ | Success: LIST_ADD:1 | ||
+ | Success: LOAD | ||
+ | Success: MODULE_PATH:/ | ||
+ | Success: PIN:1234 | ||
+ | Loaded: (pkcs11) pkcs11 engine | ||
+ | [ available ] | ||
+ | </ | ||
+ | - Now create the user certificate request the usual way and try to sign it with the CA. We have stored ours in user.csr. We will also need an identifier of the PKSC11 token, which we can get by invoking '' | ||
+ | [root@ca usercert]# openssl | ||
+ | OpenSSL> engine -t dynamic -pre SO_PATH:/ | ||
+ | (dynamic) Dynamic engine loading support | ||
+ | Success: SO_PATH:/ | ||
+ | Success: ID:pkcs11 | ||
+ | Success: LIST_ADD:1 | ||
+ | Success: LOAD | ||
+ | Success: MODULE_PATH:/ | ||
+ | Success: VERBOSE | ||
+ | Success: PIN:1234 | ||
+ | Loaded: (pkcs11) pkcs11 engine | ||
+ | PKCS#11: Initializing the engine | ||
+ | Found 2 slots | ||
+ | [ available ] | ||
+ | OpenSSL> x509 -req -engine pkcs11 -CAkeyform engine -CAkey slot_0-label_ca -CA ca.crt -days 1000 -set_serial 15 -sha256 -in user.csr -out user.crt | ||
+ | PKCS#11: Initializing the engine | ||
+ | Found 2 slots | ||
+ | engine " | ||
+ | Signature ok | ||
+ | subject=/ | ||
+ | Getting CA Private Key | ||
+ | Loading private key " | ||
+ | Looking in slot 0 for key: label=ca | ||
+ | [0] SoftHSM slot 0 | ||
+ | [1] SoftHSM slot 1 | ||
+ | Found slot: SoftHSM slot 0 | ||
+ | Found token: ca | ||
+ | Found 0 certificate: | ||
+ | No private keys found. | ||
+ | Loading private key " | ||
+ | Looking in slot 0 for key: label=ca | ||
+ | [0] SoftHSM slot 0 | ||
+ | [1] SoftHSM slot 1 | ||
+ | Found slot: SoftHSM slot 0 | ||
+ | Found token: ca | ||
+ | Found 0 certificate: | ||
+ | Found 1 private key: | ||
+ | 1 P id=ffffffa2ffffffb2 label=ca | ||
+ | ^C | ||
+ | </ | ||
+ | - Then we can verify the signing was correct:< | ||
+ | [root@ca usercert]# openssl verify -CAfile ca.crt user.crt | ||
+ | user.crt: OK | ||
+ | </ | ||
+ | - This tells us that openssl integration with the PKCS11 engine is working. To configure it in CAW, edit the '' | ||
+ | - The last step is to configure '' | ||
+ | |||
+ | ==== Using SoftHSM under non-root user ==== | ||
+ | <note warning> | ||
+ | |||
+ | We are installing SoftHSM on CentOS 7 operating system. Then, we will configure it to run under authority1 OS user. | ||
+ | - Add the EPEL repository and install necessary packages.< | ||
+ | [root@ca ~]# yum install epel-release | ||
+ | [root@ca ~]# yum install softhsm opensc engine_pkcs11 | ||
+ | </ | ||
+ | - Check if there is a system-wide configuration file.< | ||
+ | [root@ca ~]# cat / | ||
+ | # SoftHSM v2 configuration file | ||
+ | directories.tokendir = / | ||
+ | objectstore.backend = file | ||
+ | # ERROR, WARNING, INFO, DEBUG | ||
+ | log.level = INFO | ||
+ | </ | ||
+ | - We have two options: | ||
+ | * Change the system-wide configuration to point to a directory the '' | ||
+ | * Create local configuration file. This is better in cases where we want to have separate SoftHSM token storages. | ||
+ | - We go for the second option. First, we change to the authority1 user and create our directory structure and config file.< | ||
+ | [root@ca ~]# su - authority1 | ||
+ | [authority1@ca ~]$ pwd | ||
+ | / | ||
+ | [authority1@ca ~]$ mkdir -pv softhsm/ | ||
+ | mkdir: created directory ‘softhsm’ | ||
+ | mkdir: created directory ‘softhsm/ | ||
+ | [authority1@ca ~]$ chmod 750 softhsm | ||
+ | [authority1@ca ~]$ vim softhsm/ | ||
+ | [authority1@ca ~]$ cat softhsm/ | ||
+ | directories.tokendir = / | ||
+ | objectstore.backend = file | ||
+ | # ERROR, WARNING, INFO, DEBUG | ||
+ | log.level = INFO | ||
+ | </ | ||
+ | - SoftHSM is managed with the '' | ||
+ | [authority1@ca ~]$ export SOFTHSM2_CONF=/ | ||
+ | </ | ||
+ | - Now we simply call the '' | ||
+ | [authority1@ca ~]$ softhsm2-util --init-token --slot 0 --label test_slot --pin 1234 --so-pin 123456 | ||
+ | </ | ||
+ | - We can check, that new token object was created in the configured backend store.< | ||
+ | [authority1@ca ~]$ find / | ||
+ | / | ||
+ | / | ||
+ | / | ||
+ | </ | ||
+ | - SoftHSM is working! To use such configuration with CAW, edit the '' |