=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.
=Sigul Bridge Setup=
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.
1) Create an NSS database on the bridge, to hold the certificate information *AS user '''sigul ''' issue the following bridge_dir=/var/lib/* Login as sigul : <su -- This variable should be set to the location where s /bin/bash sigul resides on the system certutil -d $bridge_dir -N <-- This will generate * Generate a new NSS database for the bridge at the location of the bridge_dir variable | bridge_dir=/var/lib/sigul certutil -d $bridge_dir -N [Be sure to remember your NSS Password|]
2) Now generate the CA (Certificate Authority) certificate, to be used accross all sigul components
* Be sure to replace '''my-ca''' with whatever your desire your CA to be named, such as '''sigul-ca''' for example: certutil -d $bridge_dir -S -n my-ca -s 'CN=My CA' -t CT,, -x -v 120 <-- Be sure to replace my-ca with whatever your desire your CA to be named, such as sigul-ca for example.
3) Create a certificate for the bridge
* Be sure to replace BRIDGE_HOSTNAME with the hostname of the machine it resides on: certutil -d $bridge_dir -S -n sigul-bridge-cert -s 'CN=BRIDGE_HOSTNAME' -c my-ca -t u,, -v 120 4) Now it is time to configure the bridge, edit the config at ''/etc/sigul/bridge.conf'' * AS '''ROOT'''* Login as ROOT * Edit ''/etc/sigul/bridge.conf'': #/etc/sigul/bridge.conf [bridge] ... # You can leave most things at their default such as ports, or fas-account settings, if using FAS authentication. [daemon] ... # 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 [nss] nss- be sure password: yournsspass # This will save you having to replace BRIDGE_HOSTNAME with type it each time you start the hostname of the machine it resides onbridge ...
45) Now After editing the config and setting up the certs, it is time to configure for a test drive issue the following * AS '''ROOT''':* Start the bridgein DEBUG mode, edit the config at and all information will be logged in ''/etcvar/sigullog/bridgesigul_bridge.conf * AS ROOTlog'': sigul_bridge - You can leave most things at their default such as ports, or fasv -account settings, if using FAS authentication.v
- Under * Check the [NSS] section log file after starting sigul, if there are no errors you can set nss-passwordare good to go.* You should see the first log message in ''/var/log/sigul_bridge.log'': yournsspass < 2011-11- This will save you having 24 16:41:42,214 DEBUG: Waiting for the client to type it each time you start the bridgeconnect
* Stop the sigul_bridge CRTL- The default configuration assumes you set up a separate "sigul" user C and group; remove start the [daemon] section if you want the bridge to run as the invoking user.service: * If you use a separate user and group issue: chown sigul:sigul $bridge_dir/*.db systemctl start sigul_bridge
5) After editing the config and setting up the certs, it is time for a test drive issue the following * AS ROOT'''OPTIONAL''': sigul_bridge -v -v <-- This will start the bridge in DEBUG mode, and all information will code>tmpfs</code> might need to be logged in /var/log/sigul_bridge * Check the log file after starting sigul, if there are no errors you are good disabled to goavoid running out of space. |You should see the first log message in /var/log/sigul_bridge systemctl mask tmp.log: 2011-11-24 16:41:42,214 DEBUG: Waiting for the client to connect - Stop the sigul_bridge CRTL-C and start the service: service sigul_bridge startmount
=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 onelocally. Add bridge hostname to /etc/hosts: <IP address of sigul bridge> sigul-bridge-hostname
1) Create the NSS database on the server, to hold the certificate information *AS user '''sigul ''' issue the following* Login as sigul: su -s /bin/bash sigul
* Generate a new NSS database for the server at the location of the server_dir variable: server_dir=/var/lib/sigul <-- This variable should be set to the location where sigul resides on the system certutil -d $server_dir -N <-- This will generate a new NSS database for the server at the location of the server_dir variable | [Be sure to remember your NSS Password|]
2) Now import the CA (Certificate Authority) certificate, generated earlier on the bridge
* Issue ON THE BRIDGE as user '''sigul''': - Issue: pk12util -d $bridge_dir -o myca-server.p12 -n my-ca < * Copy ''myca-- This file should now be copied server.p12'' over to the server and deleted from the bridge afterwards * Issue ON THE SERVER as user '''sigul''': pk12util -d $server_dir -i myca-server.p12 rm myca-server.p12* Be sure to change '''my-ca''' to your CA name certutil -d $server_dir -M -n my-ca -t CT,, * The sigul CA certs should now be imported
* ON THE SERVER as user sigul - IssueBe sure to replace SERVER_HOSTNAME with the hostname of the machine it resides on: pk12util -d $server_dir -i myca.p12 rm myca.p12 certutil -d $server_dir -M S -n sigul-server-cert -s 'CN=SERVER_HOSTNAME' -c my-ca -t CTu,, <-- be sure to change my-ca to your CA namev 120
3) Now it is time to configure the server, edit the config at ''/etc/sigul/server.conf'' * AS '''ROOT'''* The sigul CA certs should now be importedLogin as ROOT certutil -d $server_dir -S -n * Edit ''/etc/sigul-/server-cert -s .conf'CN=SERVER_HOSTNAME' #/etc/sigul/server.conf [nss] bridge-c my-ca -t u,, -v 120 <-- be sure hostname: # Place sigul bridge hostname here ... [daemon] ... # The default configuration assumes you set up a separate "sigul" user and group; # remove the [daemon] section if you want the server to replace SERVER_HOSTNAME with run as the hostname of the machine it resides oninvoking user.
34) Now it is time to configure create the database for the server, edit which will hold all user and key entries issue the config at /etc/sigul/server.conf following * AS '''ROOT''' * 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.sigul_server_create_db
45) Now to create Next Add the database for the server which will hold all user and key entries issue the following initial administrator * AS '''ROOT''' sigul_server_create_db sigul_server_add_admin
56) Next Add the initial administrator After all is configured, it's time for a test drive * AS '''ROOT''':* Start the server in DEBUG mode, and all information will be logged in ''/var/log/sigul_server'': sigul_server_add_admin sigul_server -v -v
6) After all is configuredCheck the log file after starting sigul, it's time for a test drive if there are no errors you are good to go.* AS ROOT: sigul_server -v -v <-- This will start You should see the server in DEBUG mode, and all information will be logged first log message in /var/log/sigul_server.log: 2011-11-24 16:36:42,154 DEBUG: Waiting for a request
* 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 /var/log/sigul_server.log: 2011-11-24 16:36:42,154 DEBUG: Waiting for a request - Stop the sigul_server CRTL-C and start the service: service systemctl start sigul_server start '''OPTIONAL''': <code>tmpfs</code> might need to be disabled to avoid running out of space. systemctl mask tmp.mount
=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.
Add hostnames to /etc/hosts: <IP address of sigul bridge> sigul-bridge-hostname <IP address of sigul server> sigul-server-hostname 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 onelocally.
1) Create the NSS database on the client, to hold the certificate information issue the following
- * Generate a new NSS database for the server at the location of the client_dir variable client_dir=~/.sigul <-- This variable should be set to the location of sigul which is a folder under the user directory - certutil -d $client_dir -N <-- This will generate a new NSS database for the server at the location of the client_dir variable | [Be sure to remember your NSS Password|]
2) Now import the CA (Certificate Authority) certificate, generated earlier on the bridge
* Issue ON THE BRIDGE as user '''sigul''' - Issue: pk12util -d $bridge_dir -o myca-client.p12 -n my-ca < * Copy ''myca-- This file should now be copied client.p12'' over to the client and deleted from the bridge afterwards * Issue ON THE CLIENT as your own user pk12util -d $client_dir -i myca-client.p12 rm myca-client.p12* Be sure to change '''my-ca''' to your CA name certutil -d $client_dir -M -n my-ca -t CT,,
3) Next we have to generate the authentication certificate for the client* ON THE CLIENT as your usersBe sure to replace YOURUSERNAME with the user you are using on the client system - Issue: pk12util -d $client_dir -i myca.p12* OR set 'CN=YOUR FAS NAME' if using FAS authentication rm myca.p12 certutil -d $client_dir -M S -n sigul-client-cert -s 'CN=YOURUSERNAME' -c my-ca -t CTu,, <-- be sure to change my-ca to your CA namev 120
34) Next we have Now it is time to generate the authentication certificate for the clientL - certutil -d $client_dir -S -n sigul-client-cert -s 'CN=YOURUSERNAME' -c my-ca -t u,, -v 120 <-- be sure to replace YOURUSERNAME with the user you are using on configure the client system, OR if using FAS authentication set the CN=YOUR FAS NAME.
4) Now it is time to configure the client, edit the config at * Edit ''/etc/sigul/client.conf * AS '' as ROOT - You can leave most things set as default except for the following: | bridgesystem-hostname and server-hostname be sure to change those to match the hostnames of each of those machineswide configuration '''OR''' edit ''~/.sigul/client. | under [ NSS] user-name set this to the value of the admin conf'' for user your setup on the server previously | If you wish to avoid entering an NSS password upon issuing each command, issue vi # /etc/sigul/client.conf OR ~/.sigul/client.conf and add the following lines: | [nssclient] nss bridge-passwordhostname: Your NSS PASS<BRIDGE HOSTNAME> ... server-hostname: <SERVER HOSTNAME> ... user-name: <Sigul username here if it's different from your Linux login> ...
* If you wish to avoid entering an NSS password upon issuing each command, add the following lines:
[nss]
nss-password: <Your NSS PASSWORD>
5) After configuring your client, issue a test client command in DEBUG mode as follows:
- sigul -v -v list-users * 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 Help on more commands issue : sigul --help-commands for a full list
6) 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. * Please note when generating the key, it requires alot of Entropy on the server, so issue some commands to keep server busy and help it generate faster, usually a simple find / will generate enough for it to take about 2 minutes to generate the key.
'''NOTE:''' Please note when generating the key, it 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 / will generate enough for it to take about 2 minutes to generate the key.
=Sigul with koji Setup=
1) 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
2) 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.
4) 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 ##############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 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.
