Improve READMES in both packages

Signed-off-by: Max Lambrecht <[email protected]>

spiffe-tls/README.md

@@ -1,24 +1,27 @@
 # `spiffe-tls` package (experimental)
 
-This `py-spiffe` package provides TLS utilities that facilitate creating secure TLS connections leveraging SPIFFE IDs for
-authentication. It wraps [pyOpenSSL](https://pypi.org/project/pyOpenSSL/), offering easy-to-use functions for setting up
-TLS clients and servers with SPIFFE-based authentication using `X509Source` to manage and automatically update X.509
-certificates and CA trusted bundles.
+## Overview
+
+The `spiffe-tls` package, part of the `py-spiffe` library, is designed to simplify the creation of secure TLS
+connections by leveraging SPIFFE IDs for authentication. Utilizing the capabilities
+of [pyOpenSSL](https://pypi.org/project/pyOpenSSL/), this package offers
+straightforward utilities for both TLS client and server configurations. Currently in its experimental phase,
+`spiffe-tls`enables integration of [SPIFFE](https://spiffe.io)-based authentication, facilitating automatic management
+of X.509 certificates and CA trusted bundles through an `X509Source` from the [spiffe](https://pypi.org/project/spiffe/)
+package.
 
 ## Key Features
 
-- Establish TLS connections with SPIFFE ID validation.
-- Support for Mutual TLS (MTLS) and TLS with server authorization.
-- Extensible options for server and client configurations.
+- TLS connections with SPIFFE ID validation.
+- Mutual TLS (MTLS) support for authenticated client-server communication.
+- Customizable server and client TLS configurations.
 
 ## Quick Start
 
 ### Server Setup
 
-Use the `listen()` function to create a TLS server socket bound to a specified address, configured according to SPIFFE
-X.509 SVIDs.
-
 ```python
+# Create a TLS server with SPIFFE-based MTLS
 from spiffetls import listen, ListenOptions
 from spiffe import SpiffeId, X509Source
 from spiffetls.mode import ServerTlsMode
@@ -35,9 +38,8 @@ listener = listen("localhost:8443", x509_source, options)
 
 ### Client Connection
 
-Use the `dial()` function to establish a secure client connection to a TLS server.
-
 ```python
+# Establish a secure connection to a TLS server
 from spiffetls import dial
 from spiffe import SpiffeId, X509Source
 from spiffetls.tlsconfig.authorize import authorize_id
@@ -55,7 +57,14 @@ conn = dial(
 
 The package supports custom authorization functions for additional certificate validation:
 
-- `authorize_any()`: Authorizes any valid SPIFFE ID.
-- `authorize_id(expected_spiffe_id)`: Authorizes a specific SPIFFE ID.
-- `authorize_one_of(allowed_ids)`: Authorizes any SPIFFE ID in a given set.
-- `authorize_member_of(allowed_trust_domain)`: Authorizes any SPIFFE ID within a specific trust domain.
+- `authorize_any()`: Accepts any SPIFFE ID.
+- `authorize_id()`: Validates a specific SPIFFE ID.
+- `authorize_one_of()`: Allows any ID from a set of allowed SPIFFE IDs.
+- `authorize_member_of()`: Permits any ID from a specific trust domain.
+
+## Contributing
+
+We welcome contributions to the `spiffe-tls` package! Please see
+our [contribution guidelines](https://github.com/HewlettPackard/py-spiffe/blob/main/CONTRIBUTING.md) for more
+details. For feedback and issues, please submit them through
+the [GitHub issue tracker](https://github.com/HewlettPackard/py-spiffe/issues).

spiffe/README.md

@@ -2,86 +2,71 @@
 
 ## Overview
 
-The `spiffe` package, part of the `py-spiffe` library, provides Python developers with essential tools for interacting
-with the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md). It
-streamlines the management and validation of SPIFFE identities, including support
-for both [X509-SVIDs](https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md)
-and [JWT-SVIDs](https://github.com/spiffe/spiffe/blob/main/standards/JWT-SVID.md),
-and [SPIFFE Bundles](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Trust_Domain_and_Bundle.md#3-spiffe-bundles).
+The `spiffe` package, part of the `py-spiffe` library, provides [SPIFFE](https://spiffe.io) support and essential
+tools for interacting with
+the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md). It simplifies
+the management and validation of SPIFFE identities,
+supporting [X509-SVIDs](https://github.com/spiffe/spiffe/blob/main/standards/X509-SVID.md), [JWT-SVIDs](https://github.com/spiffe/spiffe/blob/main/standards/JWT-SVID.md),
+and X.509 CA and JWKS Bundles.
 
-## Usage
+# Features
 
-Below are examples demonstrating the core functionalities of the `spiffe` package.
+- Automatic Management of SPIFFE Identities: Streamlines fetching, renewing, and validation of X.509 and JWT SVIDs.
+- Seamless Integration with SPIFFE Workload API: Facilitates communication with [SPIRE](https://github.com/spiffe/spire)
+  or other SPIFFE Workload API compliant systems.
+- Continuous Update Handling: Automatically receives and applies updates for SVIDs and bundles, ensuring your
+  application always uses valid certificates.
 
-Prerequisites:
+## Prerequisites
 
-1. Running [SPIRE](https://spiffe.io/spire/) or another SPIFFE Workload API implementation.
-2. `SPIFFE_ENDPOINT_SOCKET` environment variable set to the address of the Workload
-   API (e.g. `unix:/tmp/spire-agent/public/api.sock`). Alternatively the socket address can be
-   provided programmatically.
+- A running instance of [SPIRE](https://github.com/spiffe/spire) or another SPIFFE Workload API implementation.
+- The `SPIFFE_ENDPOINT_SOCKET` environment variable set to the address of the Workload API (e.g., `unix:
+  /tmp/spire-agent/public/api.sock`), or provided programmatically.
 
-### WorkloadApiClient
+## Usage
 
-Facilitates fetching X.509 and JWT SVIDs and Bundles, and validating JWT tokens communicating with the SPIFFE Workload
-API.
+Below are examples demonstrating the core functionalities of the `spiffe` package.
+
+### WorkloadApiClient
 
 ```python
 from spiffe import WorkloadApiClient
 
-# Interacting with the Workload API to fetch SVIDs
+# Fetch X.509 and JWT SVIDs
 with WorkloadApiClient() as client:
-    # Fetch a X.509 SVID
     x509_svid = client.fetch_x509_svid()
     print(f'SPIFFE ID: {x509_svid.spiffe_id}')
-    print(f'Certificate chain: {x509_svid.cert_chain}')
-
-    # Fetch a JWT SVID
-    jwt_svid = client.fetch_jwt_svid(audience={'test'})
 
-    # Validate JWT SVID
-    validated_svid = client.validate_jwt_svid(jwt_svid.token, audience='test')
-    print(f'Validated JWT SVID for audience `test`: {jwt_svid.spiffe_id}')
-
-    # Fetch bundles of public keys
-    x509_bundles = client.fetch_x509_bundles()
-    jwt_bundles = client.fetch_jwt_bundles
+    jwt_svid = client.fetch_jwt_svid(audience={"test"})
+    print(f'SPIFFE ID: {jwt_svid.spiffe_id}')
 ```
 
 ### X509Source
 
-Automatically fetches X.509 SVIDs and Bundles from the SPIFFE Workload API and continuously receives updates. This
-ensures your application always uses valid certificates without manual intervention.
-
 ```python
 from spiffe import X509Source
-from spiffe import TrustDomain
 
+# Automatically manage X.509 SVIDs and CA bundles
 with X509Source() as source:
-    # Access the fetched X.509 SVID
     x509_svid = source.svid
     print(f'SPIFFE ID: {x509_svid.spiffe_id}')
-    print(f'Certificate chain: {[cert for cert in x509_svid.cert_chain]}')
-
-    # Access the fetched X.509 Bundle for a specific Trust Domain
-    x509_bundle = source.get_bundle_for_trust_domain(TrustDomain('example.org'))
-    print(f'X.509 Bundle for example.org: {x509_bundle}')
 ```
 
 ### JwtSource
 
-Facilitates the management and validation of JWT SVIDs and Bundles. It automatically fetches JWT SVIDs from the SPIFFE
-Workload API and validates them against the JWT bundles for their trust domains.
-
 ```python
 from spiffe import JwtSource
-from spiffe import TrustDomain
-from spiffe import JwtSvid
 
+# Manage and validate JWT SVIDs and JWKS bundles
 with JwtSource() as source:
     jwt_svid = source.fetch_svid(audience={'test'})
     print(f'SPIFFE ID: {jwt_svid.spiffe_id}')
-
-    jwt_bundle = source.get_bundle_for_trust_domain(TrustDomain('example.org'))
-    validated_svid = JwtSvid.parse_and_validate(jwt_svid.token, jwt_bundle, audience={'test'})
+    print(f'Token: {jwt_svid.token}')
 ```
 
+## Contributing
+
+We welcome contributions to the `spiffe` package! Please see
+our [contribution guidelines](https://github.com/HewlettPackard/py-spiffe/blob/main/CONTRIBUTING.md) for more
+details. For feedback and issues, please submit them through
+the [GitHub issue tracker](https://github.com/HewlettPackard/py-spiffe/issues).