cbcontrol(8)

NAME
cbcontrol

SYNOPSIS
cbcontrol command [ args ]

DESCRIPTION

cbcontrol is a process running under the super-user UID, that gets commands from a GUI program cryptobone2 and either relays these commands to an external Crypto Bone over an encrypted SSH link to a certain, fixed IP address or processes these commands itself, implementing a virtual Crypto Bone as a separate super-user process. The commands for the virtual and the external Crypto Bone are identical. The GUI (running under the ordinary user UID) sends commands to this script via the sudo mechanism and cbcontrol executes these special commands using either the cryptobone daemon on the same machine (ALL-IN-ONE mode) or sends the commands to an external device (the cryptoboneexternd daemon) via a dedicated ssh tunnel (EXTERNAL mode). The Crypto Bone software separates the user's GUI from the working of the "engine" that takes care of encrypted message transport (via safewebdrop scripts) and decryption of incoming webdrop messages and attachment files using and updating AES keys that are provided by the cryptobone daemon and stored in the database by the daemon. All cleartext files (messages and attachments) reside inside a ramdisk that can be accessed by the root user only. The GUI needs to send the appropriate commands via sudo to cbcontrol to have the task completed with access to the ramdisk that is inaccessible to everyone except the super-user root.

COMMANDS
A command is executed only if the authentication with a local secret has been successful. This local secret is stored in the Linux file system. The authentication information is provided by the program /usr/lib/cryptobone/getlocalsecret and must match a stored hash of the local secret. If it doesn't, the Crypto Bone does nothing. Almost all commands make use of the encrypted data base of secrets, which is accessible only when the cryptobone daemon (/usr/lib/cryptobone/cryptoboned) has been started at boot time. The communication between the cryptobone daemon and cbcontrol is performed through a UNIX socket (as root). These are the commands that can be sent to a Crypto Bone daemon through the UNIX socket:

USEALLINONE
    Switches to use of the ALL-IN-ONE mode. Commands are executed by the software on the client machine that runs the GUI.

USECRYPTOBONE
    Switches to use the EXTERNAL device. Commands are executed on an external device using a ssh tunnel to the external device with a dedicated IP address.

BONEIP
    Stores the IP address of the external device in the client machine in /usr/lib/cryptobone/cbb.config

GETALLINONE
    Reads the status of the Crypto Bone system.

DELETE
    Removes the stored IP address for an external device.

COPY_EXTERNAL_SECRETS
    Reads the secrets that have been generated by an external device into the client's database to enable the use of the GUI in EXTERNAL mode.

ATTACHMENT LIST
    Reads the list of attachment files that are present in the ramdisk.

ATTACHMENT COPY fileID
    Writes a copy of the attachment file into the user's home directory in $HOME/.safewebdrop This is necessary to use the attachment file with the system's helper programs, because the user has no access to the ramdisk directly.

ATTACHMENT DELETE fileID
    Deletes the attachment file in the ramdisk.

DEBUG
    Shows the output of the command "systemd status cryptoboneexternd" on the external device for debugging purposes.

EXTERNAL STATUS
    Reads the status of the external device.

FETCH
    Starts the process of downloading safewebdrop messages and attachment files from the safewebdrop server. This is done automatically every 30 seconds while the GUI is in active use.

KEY USE safewebdropaddress initialsecret
    Resets a formerly used or new contact safewebdrop address to an initial value. This destroys all message keys currently in use for the contact safewebdrop address. The only way to continue the conversation is for the contact person to do a reset with the same initial secret for your own safewebdrop address, too.

KEY RECIPIENTLIST
    Provides a list of all registered safewebdrop addresses of contacts

MESSAGE COPY messageID
    Writes a copy of the message into the user's home directory in $HOME/.safewebdrop The user is warned that copying reduces the protection on the message content, because the clear text message is no longer restricted to the ramdisk.

NETWORK STATUS CONNECT
    Shows the output of ifconfig for the ethernet adapter. Applies to the external Crypto Bone only.

NETWORK STATUS FIREWALL
    Shows the status of the internal packet filter firewall. Applies to the external Crypto Bone only.

NETWORK STATUS PING
    Checks the connection to a certain registered host on the internet to record connectivity information.

POWEROFF
    Performs a "shutdown -h now" on the external Crypto Bone. Applies to the external Crypto Bone only. The virtual Crypto Bone uses SYSTEM POWEROFF to destroy all information in the local ramdisk.

REBOOT
    Performs a reboot on the external Crypto Bone. Applies to the external Crypto Bone only.

READ DESTROY messageID
    Deletes the message from the list and deletes it in the ramdisk.

READ MESSAGELIST
    Writes a list of message names to stdout.

READ MESSAGE messageID
    Writes the specified base64-encoded message in plain text to stdout.

READ WEBDROPLIST
    Writes a list of original encrypted webdrop file names to stdout.

READ WEBDROP webdropID
    Writes the specified original encrypted webdrop text to stdout.

SETUP WID
    Writes the content of the user's safewebdrop user name to stdout.

SETUP WEBDROP
    Writes the current safewebdrop setup to stdout.

SETUP WEBDROPUSER username
    Sets the user name for a safewebdrop address that can be used to exchange encrypted messages.

SETUP WEBDROPSERVER servername
    Sets the safewebdrop server name where the username is registered as a valid user.

SETUP WEBDROPSECRET password
    Sets the password used to protect the RSA private key, which the safewebdrop transport needs to sign requests for the safewebdrop server. This information is stored in the database and can only be read by the super-user.

SETUP REGISTER
    Attempt a registration of WEBDROPUSER%WEBDROPSERVER at the safewebdrop server with the credentials stored in the database.

SETUP REGISTRATION
    Writes the registration code which was returned by the safewebdrop server to stdout.

STATUS
    Writes "active" to stdout if the masterkey is present or "waiting" if not.

SYSTEM SUSPEND
    Blocks the use of the encrypted secrets data base by renaming the masterkey. Applies to the external Crypto Bone only.

SYSTEM RESUME
    Enables the use of the encrypted secrets data base, if the masterkey was suspended. Applies to the external Crypto Bone only.

SYSTEM POWEROFF
    Destroys all information stored in the RAM disk. Not used by the external Crypto Bone. It uses POWEROFF or REBOOT instead.

SYSTEM RESTART
    Initialises the ramdisk similar to the boot process of an external Crypto Bone. This command is used only by the virtual Crypto Bone.

WRITE safewebdrop_address base64string
    Starts the process of encrypting and sending the encrypted message (and attachment file) to the specified recipient's safewebdrop address after processing the base64-encoded plain text string. A message will only be sent out, if a message key for the recipient's safewebdrop address is in the data base and if the message can be AES encrypted with this key successfully.

FILES
/usr/lib/cryptobone/cbcontrol
/usr/lib/cryptobone/cbcontrol.functions
/usr/lib/cryptobone/getlocalsecret
/usr/lib/cryptobone/secrets.sock
/usr/lib/cryptobone/ssh.sock
/usr/lib/cryptobone/database
/usr/lib/cryptobone/getlocalsecret
/usr/bin/cryptobone

SEE ALSO
cryptoboned (8)

AUTHORS
cbcontrol has been written by Ralf Senderek <innovation@senderek.ie>.

BUGS
Of course there aren't bugs, but if you find any, please sent them to innovation@senderek.ie.