cbcontrol - Man Page

cbcontrol command [ args ]

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.

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.

/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

cryptoboned (8)

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

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

activate-cryptobone(8), cryptoboned(8).