| Name | key-switcheroo JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | |
| Summary | Rotate SSH keys, stored in the cloud! |
| upload_time | 2023-08-18 19:28:05 |
| maintainer | |
| docs_url | None |
| author | Your Name |
| requires_python | >=3.11,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# key-switcheroo: SSH key rotator toolkit
## Table of Contents
1. [What is it?](#what-is-it)
2. [Features](#features)
1. [Publisher](#publisher)
2. [Retriever](#retriever)
3. [Key Rotation](#key-rotation)
3. [Where to get it](#where-to-get-it)
4. [How to use](#how-to-use)
1. [Publisher](#publisher-1)
2. [Retriever](#retriever-1)
3. [AWS Profile Management](#aws-profile-management)
5. [Dependencies](#dependencies)
6. [Configuring your SSHD](#configuring-your-sshd)
7. [Contributing](#contributing-to-key-switcheroo)
## What is it?
**key-switcheroo** is a Python package that provides tools for **easy** :smile:, **reliable** :white_check_mark:, and **secure** :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. Click [here](https://www.youtube.com/watch?v=ru8XN2EBKWY) for the video presentation.
## Features
### Publisher
The *publisher* tool 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.
### Retriever
The *retriever* tool is designed to be used by server hosts for retrieving the public keys stored by the *publisher*. When an SSH connection attempt is made, the *retriever* fetches 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 rotation
To enhance security, **key-switcheroo** supports 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 it
The source code is currently hosted on GitHub at: https://github.com/SSH-key-rotation-AWS/key-switcheroo
Binary installer for the latest released version is available at the [Python Package Index (PyPI)](https://pypi.org/project/key-switcheroo/).
`pip install key-switcheroo`
## How to use
Once the package is installed, commands can be called from the user's CLI for both the *publisher* and *retriever* using different optional arguments.
For help with command-line arguments,
`switcheroo_publish --help` or `switcheroo_publish -h`
`switcheroo_retrieve --help` or `switcheroo_retrieve -h`
### AWS Profile Management
Switcheroo uses its own AWS profile management system. This can be accessed by the base command `switcheroo_configure`. Run `switcheroo_configure -h` to 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 with `switcheroo_configure select`, delete one with
`switcheroo_configure delete`, and view your profiles with `switcheroo_configure view`.
### Publisher
When using the *publisher* for creating and publishing new SSH keys, the user has a couple of different *optional* arguments, in addition to the *required* arguments.
**Required Arguments:**
1. `hostname` - host server. This is the return value of [`socket.getfqdn()`](https://docs.python.org/3/library/socket.html#socket.getfqdn).
2. `user` - username of the connecting client
**Optional Arguments:**
- `--datastore local` or `-ds local`
- Stores the public key on the local file system
- `--datastore s3` or `-ds s3`
- Stores the public key in an S3 bucket
- If `s3` is selected, the user MUST also input `--bucket`, followed by a name for their S3 bucket
- If no `--datastore` is selected, the program will default to `s3`
- `--sshdir path/to/key/dir`
- Input the absolute path to your directory that stores the local keys (private key for S3 publisher)
- Defaults to local .ssh home directory
- `--metric aws` or `-m aws`
- Opt to have metrics published to AWS cloudwatch (time to generate keys and key count)
- `--metric file` or `-m file`
- Opt to have metrics published to the local file system (time to generate keys and key count)
- If `file` is 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`)
**Example**
`switcheroo_publish 127.0.0.1 johndoe -ds s3 --bucket mybucket --sshdir home/johndoe/.ssh -m aws`
`switcheroo_publish 127.0.0.1 johndoe --datastore local --metric file --metricpath home/switcheroo/metrics`
### Retriever
When using the *retriever* for fetching the public SSH keys, the user has a couple of different *optional* arguments, in addition to the *required* arguments.
**Required Arguments:**
1. `user` - username of the client whose key is being fetched
The `hostname` is assumed to be that of the executing computer, as retrieved by [`socket.getfqdn()`](https://docs.python.org/3/library/socket.html#socket.getfqdn).
**Optional Arguments:**
- `--datastore local` or `-ds local`
- Retrieves the public key from the local file system
- `--datastore s3` or `-ds s3`
- Retrieves the public key from the S3 bucket
- If `s3` is selected, the user MUST also input `--bucket`, followed by their S3 bucket name
- If no `--datastore` is selected, the program will default to `s3`
- `--sshdir path/to/key/dir`
- The absolute path to your directory that stores the local keys (private key for S3 publisher)
- Defaults to local .ssh home directory
**Example**
`switcheroo_retrieve johndoe --datastore s3 --bucket mybucket`
`switcheroo_retrieve johndoe -ds local --sshdir /home/johndoe/.ssh/keys`
## Configuring Your SSHD
If you want to configure your SSHD to use key-switcheroo for SSH connections, follow the following steps:
1. `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 using `pipx` to isolate the installation in a virtual environment.
2. This installs 3 binaries - `switcheroo_configure`,`switcheroo_retrieve` and `switcheroo_publish`. The exact location of these binaries depends on your OS and if you used a tool like pipx to install them
3. Configure an AWS profile using `switcheroo_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 as `aws_user`.
4. Open your `sshd_config`, or create a *.conf file in `sshd_config.d`.
5. In the config, add the following two lines:
`AuthorizedKeysCommand /path/to/switcheroo_retrieve -ds s3 --bucket [your-bucket] %u`
`AuthorizedKeysCommandUser [your user configured in step 2]`
6. 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.
## Dependencies
- [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) - Adds support for publishing public SSH keys to S3 using the AWS SDK for Python
- [pycryptodome](https://pycryptodome.readthedocs.io/en/latest/) - Provides tools for generating secure public/private SSH key pairs
## Contributing to key-switcheroo
Contributions to **key-switcheroo** are 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 the [GitHub repository](https://github.com/SSH-key-rotation-AWS/key-switcheroo).
Raw data
{
"_id": null,
"home_page": "",
"name": "key-switcheroo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Your Name",
"author_email": "you@example.com",
"download_url": "https://files.pythonhosted.org/packages/52/88/987c2501aaecd5582bc5ae23824ee1fcca7760ae724eaec734a9c3663946/key_switcheroo-1.0.2.tar.gz",
"platform": null,
"description": "# key-switcheroo: SSH key rotator toolkit\n\n\n## Table of Contents\n1. [What is it?](#what-is-it)\n2. [Features](#features)\n 1. [Publisher](#publisher)\n 2. [Retriever](#retriever)\n 3. [Key Rotation](#key-rotation)\n3. [Where to get it](#where-to-get-it)\n4. [How to use](#how-to-use)\n 1. [Publisher](#publisher-1)\n 2. [Retriever](#retriever-1)\n 3. [AWS Profile Management](#aws-profile-management)\n5. [Dependencies](#dependencies)\n6. [Configuring your SSHD](#configuring-your-sshd)\n7. [Contributing](#contributing-to-key-switcheroo)\n\n\n## What is it?\n\n**key-switcheroo** is a Python package that provides tools for **easy** :smile:, **reliable** :white_check_mark:, and **secure** :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. Click [here](https://www.youtube.com/watch?v=ru8XN2EBKWY) for the video presentation. \n\n\n## Features\n\n### Publisher\n\nThe *publisher* tool 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.\n\n### Retriever\n\nThe *retriever* tool is designed to be used by server hosts for retrieving the public keys stored by the *publisher*. When an SSH connection attempt is made, the *retriever* fetches 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.\n\n### Key rotation\n\nTo enhance security, **key-switcheroo** supports 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.\n\n\n## Where to get it\n\nThe source code is currently hosted on GitHub at: https://github.com/SSH-key-rotation-AWS/key-switcheroo\n\nBinary installer for the latest released version is available at the [Python Package Index (PyPI)](https://pypi.org/project/key-switcheroo/).\n\n`pip install key-switcheroo`\n\n\n## How to use\n\nOnce the package is installed, commands can be called from the user's CLI for both the *publisher* and *retriever* using different optional arguments.\n\nFor help with command-line arguments,\n\n\n`switcheroo_publish --help` or `switcheroo_publish -h`\n\n`switcheroo_retrieve --help` or `switcheroo_retrieve -h`\n\n### AWS Profile Management\n\nSwitcheroo uses its own AWS profile management system. This can be accessed by the base command `switcheroo_configure`. Run `switcheroo_configure -h` to get help.\n\nThe following command is used to create a profile, which is automatically used:\n\n`switcheroo_configure add --access-key [access key] --secret-access-key [secret access key] --region [region]`\n\nIf multiple profiles are added, you can select which one to use with `switcheroo_configure select`, delete one with\n`switcheroo_configure delete`, and view your profiles with `switcheroo_configure view`.\n\n### Publisher\n\nWhen using the *publisher* for creating and publishing new SSH keys, the user has a couple of different *optional* arguments, in addition to the *required* arguments.\n\n**Required Arguments:**\n1. `hostname` - host server. This is the return value of [`socket.getfqdn()`](https://docs.python.org/3/library/socket.html#socket.getfqdn).\n2. `user` - username of the connecting client\n\n**Optional Arguments:**\n- `--datastore local` or `-ds local`\n - Stores the public key on the local file system\n- `--datastore s3` or `-ds s3`\n - Stores the public key in an S3 bucket\n - If `s3` is selected, the user MUST also input `--bucket`, followed by a name for their S3 bucket\n - If no `--datastore` is selected, the program will default to `s3`\n- `--sshdir path/to/key/dir`\n - Input the absolute path to your directory that stores the local keys (private key for S3 publisher)\n - Defaults to local .ssh home directory\n- `--metric aws` or `-m aws`\n - Opt to have metrics published to AWS cloudwatch (time to generate keys and key count)\n- `--metric file` or `-m file`\n - Opt to have metrics published to the local file system (time to generate keys and key count)\n - If `file` is 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`)\n\n\n**Example**\n\n`switcheroo_publish 127.0.0.1 johndoe -ds s3 --bucket mybucket --sshdir home/johndoe/.ssh -m aws`\n\n`switcheroo_publish 127.0.0.1 johndoe --datastore local --metric file --metricpath home/switcheroo/metrics`\n\n### Retriever\n\nWhen using the *retriever* for fetching the public SSH keys, the user has a couple of different *optional* arguments, in addition to the *required* arguments.\n\n**Required Arguments:**\n1. `user` - username of the client whose key is being fetched\n\nThe `hostname` is assumed to be that of the executing computer, as retrieved by [`socket.getfqdn()`](https://docs.python.org/3/library/socket.html#socket.getfqdn).\n\n**Optional Arguments:**\n- `--datastore local` or `-ds local`\n - Retrieves the public key from the local file system\n- `--datastore s3` or `-ds s3`\n - Retrieves the public key from the S3 bucket\n - If `s3` is selected, the user MUST also input `--bucket`, followed by their S3 bucket name\n - If no `--datastore` is selected, the program will default to `s3`\n- `--sshdir path/to/key/dir`\n - The absolute path to your directory that stores the local keys (private key for S3 publisher)\n - Defaults to local .ssh home directory\n\n**Example**\n\n`switcheroo_retrieve johndoe --datastore s3 --bucket mybucket`\n\n`switcheroo_retrieve johndoe -ds local --sshdir /home/johndoe/.ssh/keys`\n\n## Configuring Your SSHD\n\nIf you want to configure your SSHD to use key-switcheroo for SSH connections, follow the following steps:\n\n1. `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 using `pipx` to isolate the installation in a virtual environment.\n\n2. This installs 3 binaries - `switcheroo_configure`,`switcheroo_retrieve` and `switcheroo_publish`. The exact location of these binaries depends on your OS and if you used a tool like pipx to install them\n\n3. Configure an AWS profile using `switcheroo_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 as `aws_user`.\n\n4. Open your `sshd_config`, or create a *.conf file in `sshd_config.d`.\n\n5. In the config, add the following two lines:\n\n `AuthorizedKeysCommand /path/to/switcheroo_retrieve -ds s3 --bucket [your-bucket] %u`\n\n `AuthorizedKeysCommandUser [your user configured in step 2]`\n\n6. Restart sshd/the system.\n\nThat's it! Now, if a public key is published to the bucket, your server will use it for SSH authentication.\n\n## Dependencies\n\n- [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) - Adds support for publishing public SSH keys to S3 using the AWS SDK for Python\n- [pycryptodome](https://pycryptodome.readthedocs.io/en/latest/) - Provides tools for generating secure public/private SSH key pairs\n\n\n## Contributing to key-switcheroo\n\nContributions to **key-switcheroo** are 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 the [GitHub repository](https://github.com/SSH-key-rotation-AWS/key-switcheroo).",
"bugtrack_url": null,
"license": "",
"summary": "Rotate SSH keys, stored in the cloud!",
"version": "1.0.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31a585c94fa9ea827e6d0e4f06aefc5d2e306cd41eca9baf4866d0b48695f90b",
"md5": "c9ee4cb74d9d67a9a177798d6461d0ed",
"sha256": "4da5fb99d5d416087a005b85a7168b7eadda9e24e30dbf0803ce7b7f942c5e85"
},
"downloads": -1,
"filename": "key_switcheroo-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9ee4cb74d9d67a9a177798d6461d0ed",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 32160,
"upload_time": "2023-08-18T19:28:04",
"upload_time_iso_8601": "2023-08-18T19:28:04.359517Z",
"url": "https://files.pythonhosted.org/packages/31/a5/85c94fa9ea827e6d0e4f06aefc5d2e306cd41eca9baf4866d0b48695f90b/key_switcheroo-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5288987c2501aaecd5582bc5ae23824ee1fcca7760ae724eaec734a9c3663946",
"md5": "6b59201bbf37db403399c1db7f40b10e",
"sha256": "ea09cb5526523dd6d2e318995d3fa4e4ab7fc4d8ecca08974f83623800b8dd65"
},
"downloads": -1,
"filename": "key_switcheroo-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6b59201bbf37db403399c1db7f40b10e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 23283,
"upload_time": "2023-08-18T19:28:05",
"upload_time_iso_8601": "2023-08-18T19:28:05.787739Z",
"url": "https://files.pythonhosted.org/packages/52/88/987c2501aaecd5582bc5ae23824ee1fcca7760ae724eaec734a9c3663946/key_switcheroo-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-18 19:28:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "key-switcheroo"
}
