Package: key-switcheroo
key-switcheroo: SSH key rotator toolkitTable of ContentsWhat is it?FeaturesPublisherRetrieverKey RotationWhere to get itHow to usePublisherRetrieverAWS Profile ManagementDependenciesConfiguring your SSHDContributingWhat is it?key-switcheroois a Python package that provides tools foreasy:smile:,reliable:white_check_mark:, andsecure:lock: SSH key management. The package contains tools to allow users to generate SSH public/private key pairs and securely store the public key either on AWS S3 or locally based on user preferences. The package also contains a tool used by the server host to retrieve and match the public keys with the corresponding private key during SSH connection attempts. Additionally, the package supports a feature for periodic rotation and swapping of public keys to enhance security. Clickherefor the video presentation.FeaturesPublisherThepublishertool offers a user-friendly interface to securely generate SSH public/private key pairs. It allows users to specify the storage location for the public key, either on AWS S3 or on their local machine. The generated private key is stored securely and can be used for SSH authentication.RetrieverTheretrievertool is designed to be used by server hosts for retrieving the public keys stored by thepublisher. When an SSH connection attempt is made, theretrieverfetches the corresponding public key associated with the private key used in the connection attempt. The tool compares the retrieved public key with the provided public key, ensuring a secure and authenticated connection.Key rotationTo enhance security,key-switcheroosupports a key rotation feature. The user simply needs to call the publisher script again with the same credentials and the program will swap and rotate the stored public keys. This process helps mitigate the risks associated with long-term key exposure and strengthens the overall security posture.Where to get itThe source code is currently hosted on GitHub at:https://github.com/SSH-key-rotation-AWS/key-switcherooBinary installer for the latest released version is available at thePython Package Index (PyPI).pip install key-switcherooHow to useOnce the package is installed, commands can be called from the user's CLI for both thepublisherandretrieverusing different optional arguments.For help with command-line arguments,switcheroo_publish --helporswitcheroo_publish -hswitcheroo_retrieve --helporswitcheroo_retrieve -hAWS Profile ManagementSwitcheroo uses its own AWS profile management system. This can be accessed by the base commandswitcheroo_configure. Runswitcheroo_configure -hto get help.The following command is used to create a profile, which is automatically used:switcheroo_configure add --access-key [access key] --secret-access-key [secret access key] --region [region]If multiple profiles are added, you can select which one to use withswitcheroo_configure select, delete one withswitcheroo_configure delete, and view your profiles withswitcheroo_configure view.PublisherWhen using thepublisherfor creating and publishing new SSH keys, the user has a couple of differentoptionalarguments, in addition to therequiredarguments.Required Arguments:hostname- host server. This is the return value ofsocket.getfqdn().user- username of the connecting clientOptional Arguments:--datastore localor-ds localStores the public key on the local file system--datastore s3or-ds s3Stores the public key in an S3 bucketIfs3is selected, the user MUST also input--bucket, followed by a name for their S3 bucketIf no--datastoreis selected, the program will default tos3--sshdir path/to/key/dirInput the absolute path to your directory that stores the local keys (private key for S3 publisher)Defaults to local .ssh home directory--metric awsor-m awsOpt to have metrics published to AWS cloudwatch (time to generate keys and key count)--metric fileor-m fileOpt to have metrics published to the local file system (time to generate keys and key count)Iffileis selected, the user CAN also input--metricpath, followed by path to a directory to store the metrics in (default is{user's home}/switcheroo_app_data/metrics)Exampleswitcheroo_publish 127.0.0.1 johndoe -ds s3 --bucket mybucket --sshdir home/johndoe/.ssh -m awsswitcheroo_publish 127.0.0.1 johndoe --datastore local --metric file --metricpath home/switcheroo/metricsRetrieverWhen using theretrieverfor fetching the public SSH keys, the user has a couple of differentoptionalarguments, in addition to therequiredarguments.Required Arguments:user- username of the client whose key is being fetchedThehostnameis assumed to be that of the executing computer, as retrieved bysocket.getfqdn().Optional Arguments:--datastore localor-ds localRetrieves the public key from the local file system--datastore s3or-ds s3Retrieves the public key from the S3 bucketIfs3is selected, the user MUST also input--bucket, followed by their S3 bucket nameIf no--datastoreis selected, the program will default tos3--sshdir path/to/key/dirThe absolute path to your directory that stores the local keys (private key for S3 publisher)Defaults to local .ssh home directoryExampleswitcheroo_retrieve johndoe --datastore s3 --bucket mybucketswitcheroo_retrieve johndoe -ds local --sshdir /home/johndoe/.ssh/keysConfiguring Your SSHDIf you want to configure your SSHD to use key-switcheroo for SSH connections, follow the following steps:pip install key-switcheroo. Note that installing packages onto the system may cause issues, and should be done with care. You may want to consider usingpipxto isolate the installation in a virtual environment.This installs 3 binaries -switcheroo_configure,switcheroo_retrieveandswitcheroo_publish. The exact location of these binaries depends on your OS and if you used a tool like pipx to install themConfigure an AWS profile usingswitcheroo_configure add. Note that the user that configures this profile will be the user retrieving keys - SSH reccomends having a separate user to do this, such asaws_user.Open yoursshd_config, or create a *.conf file insshd_config.d.In the config, add the following two lines:AuthorizedKeysCommand /path/to/switcheroo_retrieve -ds s3 --bucket [your-bucket] %uAuthorizedKeysCommandUser [your user configured in step 2]Restart sshd/the system.That's it! Now, if a public key is published to the bucket, your server will use it for SSH authentication.Dependenciesboto3- Adds support for publishing public SSH keys to S3 using the AWS SDK for Pythonpycryptodome- Provides tools for generating secure public/private SSH key pairsContributing to key-switcherooContributions tokey-switcherooare welcome! If you encounter any issues, have suggestions, or would like to add new features, please feel free to open an issue or submit a pull request on theGitHub repository.