Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: rewrite README #624

Closed
wants to merge 1 commit into from
+41 −389
Closed

docs: rewrite README #624

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# securesystemslib

[![CI](https://github.com/secure-systems-lab/securesystemslib/workflows/Run%20Securesystemslib%20tests/badge.svg)](https://github.com/secure-systems-lab/securesystemslib/actions?query=workflow%3A%22Run+Securesystemslib+tests%22+branch%3Amain)

A cryptography interface to sign and verify
[TUF](https://theupdateframework.io) and [in-toto](https://in-toto.io)
metadata.
Comment on lines +5 to +7
Copy link
Collaborator

@jku jku Aug 31, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is more honest but maybe goes a bit too far? It's not that you can't sign anything you want...

I've added a bit of hopfully still honest marketing -- also mentioned some tech we use so that the "default installation supports ed25519 only" doesn't scare people away.

Suggested change
A cryptography interface to sign and verify
[TUF](https://theupdateframework.io) and [in-toto](https://in-toto.io)
metadata.
Securesystemslib is a cryptography interface for signing and verifying digital signatures. It is developed for the [TUF](https://theupdateframework.io) and [in-toto](https://in-toto.io) projects: the key and signature containers are compatible with metadata formats from those projects.
Under the hood Securesystemslib is able to use various digital signing systems (e.g. [cryptography](https://pypi.org/project/cryptography/), PIV hardware keys and multiple cloud based key management systems).


## Installation

The default installation supports [pure-Python `ed25519` signature
verification](https://github.com/pyca/ed25519) only. To enable other schemes and
signature creation, `securesystemslib` can be installed with *extras*. See
[pyproject.toml](pyproject.toml) for available *optional dependencies*.

```bash
# Install with ed25519, RSA, ECDSA sign and verify support
pip install securesystemslib[crypto]
Comment on lines +17 to +18
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"crypto" is such a confusing term here that maybe worth adding another example

Suggested change
# Install with ed25519, RSA, ECDSA sign and verify support
pip install securesystemslib[crypto]
# Install with ed25519, RSA, ECDSA sign and verify support
pip install securesystemslib[crypto]
# ...or with HSM (e.g. Yubikey) support
pip install securesystemslib[hsm]

```

## Usage
[python-securesystemslib.readthedocs.io](https://python-securesystemslib.readthedocs.io)

## Contact
- Questions and discussions:
[`#securesystemslib-python`](https://cloud-native.slack.com/archives/C05PF3GA7AL)
on [CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf)
- Security issues: [*Draft a new security
advisory*](https://github.com/secure-systems-lab/securesystemslib/security/advisories/new)
Comment on lines +28 to +29
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Security issues: [*Draft a new security
advisory*](https://github.com/secure-systems-lab/securesystemslib/security/advisories/new)
- Security issues: [*Report a vulnerability*](https://github.com/secure-systems-lab/securesystemslib/security/advisories/new)

- Other issues and requests: [*Open a new
issue*](https://github.com/secure-systems-lab/securesystemslib/issues/new)

## Testing
`tox` is used for testing. It can be installed via
[pip](https://tox.wiki/en/4.9.0/installation.html#via-pip) and executed from the
command line in the root of the repository.

```bash
tox
```
Loading