Koji/SigulInstall

Sigul Overview

Sigul is a package signing server, which aids in signing RPM's either multiple, or single files. All keys reside solely on the sigul server, no user has access to any of the private or public keys. All communication with the server is done through the sigul bridge, it acts as the gateway between the client, and server. This isolates the server, preventing any unwanted access from outside sources other than the bridge. The sigul client once configured allows users to sign rpm's with keys created on the sigul server, by sending commands first to the bridge, which then relays to the server.

Installation

This part is very very easy

# yum install seagul
# su - sigul -s /bin/bash -c 'mkdir /var/lib/sigul/{bridge,server}'

Sigul Bridge Setup

What the bridge does: The bridge acts as the central gateway for sigul. The bridge is the only component which speaks to the server, if you are issuing any server bound commands from the client, your actually sending them to the bridge which in turn fires them off to the server, recieves the reply, and sends that back to the client. The bridge also functions as the gateway for Koji, when signing packages from a koji instance, the bridge speaks to the kojihub with authentication by way of a Proxy user, such as Kojiweb. We will be getting into the koji side of things a bit more later in this doc.

To begin setup, we have generate the certs which will be used for all sigul systems to authenticate between eachother. The bridge will be used as the CA for internal sigul communications.

Be sure to remember all your NSS Password
FAS is Fedora account system, so no need for a personnal sigul server

Password summary

	Bridge	Server	Client
NSS Certificate DB	bridgensspasswd	servernsspasswd	clientnsspasswd
PKCS12 Certificate	--------------	server	client

Administrator summary

Login	Password
didier	sigadmpasswd

Operations with sigul account

All following commands must be done with sigul account

# su - sigul -s /bin/bash

Set shell for user sigul permanently

# usermod -s /bin/bash sigul

Create an NSS database on the bridge, to hold the certificate information

 $ bridge_dir=/var/lib/sigul/bridge

Generate a new NSS database for the bridge at the location of the bridge_dir variable

 $ certutil -d $bridge_dir -N

Generate the CA (Certificate Authority) certificate, to be used accross all sigul components

CN must be the full qualified domain name of the server where bridge is hosted.

 $ certutil -d $bridge_dir -S -n sigul-ca -s 'CN=Sigul CA' -t CT,, -x -v 120

Create a certificate for the bridge

CN must be the fully qualified domain name of the server where sigul server is hosted.

 $ certutil -d $bridge_dir -S -n sigul-bridge-cert -s 'CN=bridge.b2pweb.com' -c sigul-ca -t u,, -v 120

Operations with root account

Now it is time to configure the bridge, edit with the root account the config at <path>/etc/sigul/bridge.conf</path>

• You can leave most things at their default such as ports, or fas-account settings, if using FAS authentication.
• Under the [NSS] section you can set nss-password: yournsspass
• The default configuration assumes you set up a separate "sigul" user and group. Remove the [daemon] section if you want the bridge to run as the invoking user.
• If you use a separate user and group issue: chown sigul:sigul $bridge_dir/*.db

After editing the config and setting up the certs, it is time for a test drive issue the following

[root@bridge] # sigul_bridge -v -v

This will start the bridge in DEBUG mode, and all information will be logged in <path>/var/log/sigul_bridge.log</path>

Check the log file after starting sigul, if there are no errors you are good to go.

You should see the first log message in <path>/var/log/sigul_bridge.log</path>

2011-11-24 16:41:42,214 DEBUG: Waiting for the client to connect

Stop the sigul_bridge CRTL-C

Now we can start the service, and enable daemon start at boot

for distribution with systemd

[root@bridge] # systemctl start sigul_bridge.service
[root@bridge] # systemctl enable sigul_bridge.service

for distribution with sysVinit

[root@bridge] # service sigul_bridge start
[root@bridge] # chkconfig sigul_bridge on

Sigul Server Setup

What the server does: The server is completley cutoff from the rest of the world, It should be firewalled off except for incoming ports from the bridge, and should only be able to speak to the bridge, for max security, ensure it has no external access from other machines or even the web. It hold's all of the key files used for signing the RPMS, so no other users will have access to the key files, the server is the only system that knows the keys.

To begin setup, we have to follow a similar process to the bridge with NSS, except that we will import the CA cert generated on the bridge, not generate a new one.

Operations with sigul account

Create the NSS database on the server, to hold the certificate information with the user sigul account

First we set the location where sigul resides on the system

[sigul@server] $ server_dir=/var/lib/sigul
[sigul@server] $ certutil -d $server_dir -N

This will generate a new NSS database for the server at the location of the server_dir variable

Import the CA (Certificate Authority) certificate, generated earlier on the bridge

ON THE BRIDGE as user sigul

[sigul@bridge] $ pk12util -d $bridge_dir -o sigulca.p12 -n sigul-ca

This file should now be copied over to the server and deleted from the bridge afterwards

ON THE SERVER as user sigul

The sigul CA certs should now be imported

[sigul@server] $ pk12util -d $server_dir -i sigulca.p12
[sigul@server] $ rm sigul.p12
[sigul@server] $ certutil -d $server_dir -M -n sigul-ca -t CT,,

CN must be the fully qualified domain name of the server where sigul server is hosted.

[sigul@server] $ certutil -d $server_dir -S -n sigul-server-cert -s 'CN=server.b2pweb.com' -c sigul-ca -t u,, -v 120

Operations with root account

Now it is time to configure the server, edit the config at <path>/etc/sigul/server.conf</path> with root account
Note the default ports. Edit at least bridge-hostname and the [nss] section. The default configuration assumes you set up a separate "sigul" user and group; remove the [daemon] section if you want the server to run as the invoking user.

Now to create the database for the server which will hold all user and key entries issue the following * AS ROOT

[root@server] # sigul_server_create_db

Next Add the initial administrator

[root@server] # sigul_server_add_admin

After all is configured, it's time for a test drive

Start the server in DEBUG mode, and all information will be logged in <path>/var/log/sigul_server.log</path>

[root@server] # sigul_server -v -v

Check the log file after starting sigul server, if there are no errors you are good to go.

You should see the first log message in <path>/var/log/sigul_server.log:</path>

2011-11-24 16:36:42,154 DEBUG: Waiting for a request

Now we can start the service, and enable daemon start at boot

for distribution with systemd

[root@server] # systemctl start sigul_server.service
[root@server] # systemctl enable sigul_server.service

for distribution with sysVinit

[root@server] # service sigul_server start
[root@server] # chkconfig sigul_server on

Sigul Client Setup

What the client does: The client is simply that, a client, it has certs necessary for it to be authenticated with the sigul bridge to issue commands as the sigul admin, to the server. All client commands are sent to bridge which in turn talks to either koji or the server depending on what the clients request is.

To begin setup, we have to follow a similar process to the bridge with NSS, except that we will import the CA cert generated on the bridge, not generate a new one.

ON THE BRIDGE as user sigul

$ pk12util -d $bridge_dir -o sigulca.p12 -n sigul-ca

This file should now be copied over to the client and deleted from the bridge afterwards

ON THE BRIDGE as root

Copy <path>/var/lib/sigul/sigulca.p12</path> to the user home, and change owner of it.

# cp /var/lib/sigul/sigulca.p12 /home/USER/
# chown USER /home/USER/sigulca.p12

ON THE CLIENT as your users

Create the NSS database on the client, to hold the certificate information issue the following

$ client_dir=~/.sigul
$ mkdir $client_dir
$ certutil -d $client_dir -N

Import the CA (Certificate Authority) certificate, generated earlier on the bridge

$ pk12util -d $client_dir -i sigulca.p12
$ rm sigulca.p12
$ certutil -d $client_dir -M -n sigul-ca -t CT,,

Generate the authentication certificate for the client.

CN must be the user account

$ certutil -d $client_dir -S -n sigul-client-cert -s 'CN=didier' -c sigul-ca -t u,, -v 120

Operations with root account

Configure the client, edit the config at <path>/etc/sigul/client.conf</path>

• You can leave most things set as default except for the following:
• bridge-hostname and server-hostname be sure to change those to match the hostnames of each of those machines.
• under [ NSS] user-name set this to the value of the admin user your setup on the server previously
• If you wish to avoid entering an NSS password upon issuing each command, issue vim <path>~/.sigul/client.conf</path> and add the following lines:

[nss]
nss-password: Your NSS PASS

After configuring your client, issue a test client command as follows:

# sigul list-users

Available Commands
This should return a list of users on the server, at this point it should only really display the one admin user created before. For more commands issue

$ sigul --help-commands
delete-key          Delete a key
modify-key-user     Modify user's key access
list-users          List users
grant-key-access    Grant key access to a user
sign-text           Output a cleartext signature of a text
import-key          Import a key
new-user            Add a user
sign-rpm            Sign a RPM
list-keys           List keys
sign-data           Create a detached signature
revoke-key-access   Revoke key acess from a user
user-info           Show information about a user
change-passphrase   Change key passphrase
list-key-users      List users that can access a key
new-key             Add a key
modify-user         Modify a user
sign-rpms           Sign one or more RPMs
modify-key          Modify a key
delete-user         Delete a user
key-user-info       Show information about user's key access
get-public-key      Output public part of the key

Now, we can create a key or import an existing key.

create a new key

Create an initial key once you are able to issue commands to sigul, issue the following:

$ sigul new-key -h

This will output the options that can be used with the key creation, use the ones you want, and generate the key.*

$ sigul new-key --name-real='Service Reseaux et Systemes' --name-comment='SRS' --name-email='srs@b2pweb.com'--key-admin didier srs

Generating enough entropy
Generating the key requires a lot of Entropy on the server, so issue some commands to keep server busy and help it generate faster, usually a simple

find / > /dev/null 2>&1

will generate enough for it to take about 2 minutes to generate the key.

Import an existing key

$ sigul import-key 'Service Reseaux et Systemes' ~/.gnupg/secring.gpg

Sigul with koji Setup

How it works with koji: Sigul can be used with koji to sign multiple packages in a koji instance. Provided you have your client user already configured with Koji, it's a simple matter of configuring the proxy user on sigul_bridge. When a client issues a sign command for a koji instance, the bridge is what actually queries koji on behalf of the client user, and grabs the rpm's to be signed from sigul by way of the kojiweb user. The only thing you must ensure is that your koji client user as admin privileges on the koji server, and the bridge takes care if the rest.

As ROOT on the sigul bridge, edit /etc/sigul/bridge.conf edit the koji section as follows:

[koji]
koji-config: /path/to/koji/config/file  <-- The config file should be that of koji web

The koji configuration file and certs can reside under any directory that sigul has atleast read privileges on. The kojiweb certificates that allow kojiweb to authenticate with koji must be copied to this directory, along with the config file which points to the koji instance, as well as the kojiweb certs needed for it to authenticate.

After doing the above restart the bridge, and you should now be able to pull packages from koji and sign them.

To test issue the following on the client, to download and RPM from koji - sign it - and store it locally - Just as a test for koji connectivity and authentication:

$ sigul sign-rpm -o signed.rpm key_name unsigned.rpm <-- key_name should be the name of the sigul key you setup previously.
   

If the above is successful, you will have an rpm named signed.rpm in the directory you are working in.

Sigul Client Config Script

The following is an optional script, which can be used to aide in the quick setup of sigul clients, when not using FAS Authentication:

• Note that the user must first have an account created on the sigul server, this script is solely to setup the client side certificates

 #!/bin/bash
 #Variables### And initial setup#######
 mkdir ~/.sigul
 client_dir=~/.sigul
 user=$(whoami)  
 ####################
 echo
 ############################Begin Certificate imports
 echo "======================="
 echo "Setting up NSS Database"
 echo "======================="
 certutil -d $client_dir -N
 echo
 echo "==================="
 echo "Downloading CA Cert"
 echo "==================="
 wget http://someurl.com/sigul/sigulca.p12 <-- Substitute with a path or url of your exported .p12
 echo
 echo "=================="
 echo "Importing CA certs"
 echo "=================="
 pk12util -d $client_dir -i sigulca.p12
 certutil -d $client_dir -M -n sigul-ca -t CT,,
 echo
 echo "======================"
 echo "Generating Client cert"
 echo "======================"
 certutil -d $client_dir -S -n sigul-client-cert -s "CN=$user" -c sigul-ca -t u,, -v 120
 echo
 echo "======================"
 #########End certificate imports########
 ########################################
 #########NSS password Saver#############
 read -p "Would you like to save your nss pass to ~/.sigul/client.conf [y/n]: " nsspasssel
 #########User Input conditional#########
 if [ $nsspasssel == "y" -o $nsspasssel == "Y" ]; then
 echo "Enter your NSS password One more time: "
 read -s nsspass
 echo "[nss]" > ~/.sigul/client.conf
 echo "nss-password: $nsspass" >> ~/.sigul/client.conf
 echo
 echo "==========="
 echo "Cleaning up"
 echo "==========="
 rm sigulca.p12
 else
 echo
 echo "==========="
 echo "Cleaning up"
 echo "==========="
 rm sigulca.p12
 fi
 #########################################\

• If you plan to use FAS Authentication, run sigul_setup_client as the user you wish to setup.

Next

Next is to use the Sigul signing server