Manual/Quickstart/Installation
From OpenXPKI Wiki
Contents |
Installation
Compilation and Module installation
Assuming you've gotten a source tree from somewhere (i.e. either an official release tar-ball or a Subversion checkout), enter the trunk/perl-modules/core/trunk directory. Run "perl Makefile.PL" to create a Makefile. If this should fail, please make sure that you have installed all required Perl modules. If you don't, you can install them using either software packages from your distribution or by using the CPAN shell. The CPAN package Bundle::OpenXPKI can be used to download the minimal set of required packages (run "perl -MCPAN -e 'install Bundle::OpenXPKI'"). If it works, you can compile OpenXPKI using "make". Once that is taken care of, make sure to run "make test" to see if the compiled OpenXPKI runs correctly. "make install" completes the installation of the Perl modules. Note that if you want to install OpenXPKI locally, i.e. into your home directory, you can run "perl Makefile.PL PREFIX=directory" in the first step to prepare for an installation below directory.
Now you have all the required modules for the server installed. As the administrative tools use code of the OpenXPKI client as well, you need to install the corresponding modules, too. They come in handy later on when you want to set up a client (such as the Mason-based web interface) as well. Change to the trunk/clients/perl/OpenXPKI-Client directory and repeat the same steps as above, again using "perl Makefile.PL PREFIX=directory" if necessary.
Initial (pre-deployment) configuration
Before being able to run the server, the administrative tools and the (base) configuration have to be deployed. To install them, change into the trunk/deployment directory. Run "./configure", or (if you want to install into a local directory) "./configure --prefix directory". Then, run "make" and "make install" to install the tools.
Deployment
To install the meta configuration file (openxpki.conf), run openxpkiadm deploy --template quickstart. Follow the instructions and run openxpki-configure. This is an interactive tool that allows you to specify some of the basic configuration options. The most important options that you need to set right now are the location of your openssl binary (defaults to /usr/bin/openssl) and your database configuration. Exit the tool and allow it to write the modified configuration. Depending on the deployment style, you now have one huge config.xml or a number of smaller XML files in your etc/openxpki directory. These are the files that are actually used by the OpenXPKI server and which you can modify later to set up your desired behaviour. After having set up a database using your favourite tool for your favourite DBMS, you should run openxpkiadm initdb to set up the database schema. If everything goes right, try to start the OpenXPKI server using openxpkictl start. If you see "DONE." in the last line of output, this works and the OpenXPKI server is up and running. Stop it for now using openxpkictl stop. If it goes wrong, please check your PERL5LIB environment variable. This variable needs to include the location where your Perl modules where installed (which depends on your PREFIX setting).
Setting up the web interface
So now you've got a working server, but of course you can not see very much of it, which is why the installation of the web interface will be the next step. Change into the trunk/clients/perl/OpenXPKI-Client-HTML-Mason directory and run "perl Makefile.PL" (again adding the PREFIX option if necessary), "make" and "make install". This installs the needed client modules. In the next step, copy the htdocs directory to a path of your liking that is readable by your webserver. We will refer to this directory as the (Mason) component root later on.
For the rest of this section, we assume you are using Apache as your webserver. Installation under different webservers is possible, but you are largely on your own here. There are two different options how to install the OpenXPKI Mason client - either using mod_perl or using CGI. If you have mod_perl available, go for it, as it is much faster than using CGI. CGI is not recommend for production use, but to quickly try out OpenXPKI, it works.
Installing using mod_perl
Use the eg/openxpki-mason-mod_perl.conf file as a boilerplate for your Apache configuration. You need to change five variables defined in this file. The first one is the MasonDataDir variable, which should point to a directory that is writable by your webserver user. This is a directory where Mason temporarily caches its components. The second one is the MasonCompRoot variable, which should point to the component root that you chose earlier. Furthermore, you need to set up OPENXPKI_SOCKET_FILE to point to your OpenXPKI socket file. Note that this file needs to be readable and writable by both your OpenXPKI user as well as the webserver user - the easiest way to achieve this is putting them in a common group. You can look up the location of the socket file in your config.xml. The fourth variable is OPENXPKI_MASON_SESSION_DIR which is a directory for the client sessions - this is supposed to be read-/writable by your Apache user only. The last variable is OPENXPKI_LOCALE_PREFIX, which needs to point to your locale directory if you have installed it in a non-standard path (see the next step). (Re)start your Apache and you should be up and running, but you won't be able to do much yet because you do not have a CA certificate yet.
Installing the internationalization files
If you have looked at the webserver after the last step, you may have noticed that it does not speak any language yet, but only shows so-called I18N-identifiers. You will need to go to the trunk/i18n directory and run "make" and "make install" to install the gettext files. If you use a local installation, you can run "PREFIX=directory make install" instead of "make install".
Setting up the CA certificate and key
To be able to issue certificates, you will of course need a CA certificate. For the quickstart, we will assume that you want a single CA certificate with no intermediaries (which are strongly suggested for production use, though). For now, we will assume that you want to create a software key using a single password. Other methods such as threshold secret sharing or using HSMs are available too but beyond the scope of this quickstart guide.
Creating a new CA key
OpenXPKI is able to use the same password for different keys and thus has the concept of so-called secret groups. If you have a look at your newly created config.xml, you will see a definition for the secret group with ID default. This secret group is also referenced as the group used for unlocking your CA key token in token.xml. You need to specify the ID of the secret group when generating a new key using openxpkiadm key generate. Typically, the required command line will look like this: openxpkiadm key generate --realm realm --group default. Follow the directions to select the type and parameters for your keys. As a start, using an RSA key with 2048 bit key length and AES256 as the key encryption algorithm would be a reasonable choice. You can check if everything went fine by using the openxpkiadm key list --realm realm command - all listed keys should now be prefixed with a plus sign.
Creating and installing a new CA certificate
Using the new key, you will need to create a new CA certificate. The quickest way is doing so using OpenSSL. Create a minimal config file (openssl.cnf) with the following content:
[ ext ] keyUsage = critical, cRLSign, keyCertSign basicConstraints = critical,CA:true subjectKeyIdentifier = hash [ req ] distinguished_name = ca_dn [ ca_dn ] countryName = "Country code" organizationName = "Organization" organizationalUnitName = "Organizational Unit" commonName = "Common name"
Then, run the following command: openssl req -config openssl.cnf -extensions ext -days validity_length -new -x509 -key /path/to/your/cakey.pem -out cacert.pem. After answering the questions, a new CA certificate should be available in cacert.pem. You will need to import this certificate into the OpenXPKI database. To do so, run openxpkiadm certificate import --file /path/to/your/cacert.pem . If that is successful, you will see an identifier for the certificate. To reference the certificate within the OpenXPKI configuration, you can either use the identifier directly or use a so-called alias, which is just a symbolic name for the identifier. In your freshly deployed config.xml, you should find a certificate section that references an alias and a realm. To set the alias, use openxpkiadm certificate alias --realm configured_realm --alias configured_alias --identifier identifier. Once you have restarted the OpenXPKI server using openxpkictl stop; openxpkictl start, your CA should be up and running. You can check that using the web interface - use the Download → CA certificates menu to see if your CA is listed as usable.
