diff --git a/rcgen/CHANGELOG.md b/rcgen/CHANGELOG.md index 560b3bca..7592f1de 100644 --- a/rcgen/CHANGELOG.md +++ b/rcgen/CHANGELOG.md @@ -1,6 +1,75 @@ # Changes +## Release 0.13.0 - March XX, 2024 + +Breaking changes: + +- The API used to create/issue key pairs, certificates, certificate signing + requests (CSRs), and certificate revocation lists (CRLs) has been + restructured to emphasize consistency and avoid common errors with + serialization. + + For each concrete type (cert, CSR, CRL) the process is now the same: + + 0. generate or load a key pair and any information about issuers required. + 1. create parameters, customizing as appropriate. + 2. call a generation `fn` on the parameters, providing subject key pair and + issuer information and as appropriate. + 3. call serialization `fn`s on the finalized type, obtaining DER or PEM. + + For more information, see [rcgen/docs/0.12-to-0.13.md]. + +- Throughout the API DER inputs are now represented using types from the Rustls + `rustls-pki-types` crate, e.g. `PrivateKeyDer`, `CertificateDer`, + `CertificateSigningRequestDer`. Contributed by + [Tudyx](https://github.com/tudyx). + +- String types used in `SanType` and `DnValue` enums for non-UTF8 string types + have been replaced with more specific types that prevent representation of + illegal values. E.g. `Ia5String`, `BmpString`, `PrintableString`, + `TeletexString`, and `UniversalString`. Contributed by + [Tudyx](https://github.com/tudyx). + +- Method names starting with `get_` have been renamed to match Rust convention: + `CertificateRevocationList::get_params()` -> `params()` + `Certificate::get_params()` -> `params()` + `Certificate::get_key_identifier()` -> `Certificate::key_identifier()` + `Certificate::get_times()` -> `Certificate::times()` + +Added: + +- RSA key generation support has been added. This support requires using the + `aws-lc-rs` feature. By default using `KeyPair::generate()` with + an RSA `SignatureAlgorithm` will generate an RSA 2048 keypair. See + `KeyPair::generate_rsa_for()` for support for RSA 2048, 3072 and 4096 key sizes. + +- Support for ECDSA P521 signatures and key generation has been added when using + the `aws-lc-rs` feature. Contributed by [Alvenix](https://github.com/alvenix). + +- Support for loading private keys that may be PKCS8, PKCS1, or SEC1 has been + added when using the `aws-lc-rs` feature. Without this feature private keys + must be PKCS8. See `KeyPair::from_pem_and_sign_algo()` and + `KeyPair::from_der_and_sign_algo()` for more information. Contributed by + [Alvenix](https://github.com/alvenix). + +- Support has been added for Subject Alternative Name (SAN) names of type + `OtherName`. Contributed by [Tudyx](https://github.com/tudyx). + +- Support has been added for specifying custom "other" OIDs in extended key + usage. Contributed by [Tudyx](https://github.com/tudyx). + +- Support has been added for building rcgen _without_ cryptography by omitting + the new (default-enabled) `crypto` feature flag. Contributed by + [corrideat](https://github.com/corrideat). + +- Support for using `aws-lc-rs` in `fips` mode can now be activated by using the + `fips` feature in combination with the `aws-lc-rs` feature. Contributed by + [BiagioFesta](https://github.com/biagiofesta). + +- A small command-line tool for certificate generation (`rustls-cert-gen`) was + added. Contributed by [tbro](https://github.com/tbro). + ## Release 0.12.1 - January 25th, 2024 - RFC 5280 specifies that a serial number must not be larger than 20 octets in diff --git a/rcgen/docs/0.12-to-0.13.md b/rcgen/docs/0.12-to-0.13.md new file mode 100644 index 00000000..457c4231 --- /dev/null +++ b/rcgen/docs/0.12-to-0.13.md @@ -0,0 +1,90 @@ +# Rcgen 0.12 to 0.13 Migration Guide + +This document is a meant to be a helpful guide for some of the API changes made +between rcgen 0.12 and 0.13. For information on other changes in 0.13 see +[rcgen/CHANGELOG.md]. + +## Key Pairs + +* Previously it was possible to have certificate generation automatically create + a subject `KeyPair` for you by leaving the `key_pair` field of + `CertificateParams` empty, and retrieving the generated `KeyPair` from + a `Certificate` created with the `CertificateParams` by calling + `Certificate::get_key_pair()`. + + To offer more consistency and to keep the `CertificateParams` and `Certificate` + types from holding private key data, the new API requires you handle `KeyPair` + creation yourself. See `CertifiedKey`, `KeyPair::generate()`, + `KeyPair::generate_for()` and `KeyPair::generate_rsa_for()` for more information. + +* Serializing a `Certificate`'s `KeyPair` to DER or PEM was previously done by + calling `Certificate::serialize_private_key_der()` or + `Certificate::serialize_private_key_pem()`. This is now handled by calling + `KeyPair::serialize_der()` or `KeyPair::serialize_pem()`. + +## Certificates + +* For quick-and-easy self-signed certificate issuance, + `generate_simple_self_signed` now returns a `CertifiedKey` in the success case + instead of a `Certificate`. The self-signed `Certificate` can be accessed in + the `cert` field of `CertifiedKey`, and the generated subject key pair in + `key_pair`. + +* Custom self-signed certificate issuance was previously done by + constructing `CertificateParams` and calling `Certificate::from_params()` to + create a `Certificate`. This is now done by calling + `CertificateParams::self_signed()`, providing a subject `KeyPair` of your + choosing. + +* Custom certificate issuance signed by an issuer was previously done by + constructing `CertificateParams`, calling `Certificate::from_params()` and + then choosing the issuer at serialization time. This is now done ahead of + serialization by calling `CertificateParams::signed_by()` and providing + a subject `KeyPair` as well as an issuer `Certificate` and `KeyPair`. + +* Previously certificate serialization was done by calling + `Certificate::serialize_der()`, `Certificate::serialize_pem()`, + `Certificate::serialize_der_with_signer()` or + `Certificate::serialize_pem_with_signer()`. Each time a serialization fn was + called a new certificate was issued, leading to confusion when it was desired + to serialize the same certificate in two formats. In the new API issuance is + handled by `CertificateParams` fns and the generated `Certificate` will not change + when serialized. You can serialize it to PEM by calling `Certificate::pem()`, + or access the DER encoding by calling `Certificate::der()`. + +## Certificate Signing Requests (CSRs) + +* Previously it was only possible to create a new CSR by first issuing + a `Certificate` from `CertificateParams`, and calling + `Certificate::serialize_request_pem()` or + `Certificate::serialize_request_der()`. In the updated API you can create + a `CertificateSigningRequest` directly from `CertificateParams` by calling + `CertificateParams::serialize_request` and providing a subject `KeyPair`. You + may serialize the CSR to DER or PEM by calling + `CertificateSigningRequest::der()` or `CertificateSingingRequest::pem()`. + +* To load a CSR from an existing PEM/DER copy with the old API required + calling `CertificateSingingRequest::from_pem()` or + `CertificateSigningRequest::from_der()`. The new API introduces + a `CertificateSingingRequestParams` type that can be created using + `CertificateSigningRequestParams::from_pem()` or + `CertificateSingingRequest::from_der()`. + +* To issue a certificate from an existing CSR with the old API required calling + `CertificateSigningRequest::serialize_der_with_signer()` or + `CertificateSigningRequest::serialize_pem_with_signer(). In the new API, call + `CertificateSigningRequestParams::signed_by()` and provide an issuer + `Certificate` and `KeyPair`. + +## Certificate Revocation Lists (CRLs) + +* Previously a `CertificateRevocationList` was created by calling + `CertificateRevocationList::from_params()`. This is now done by calling + `CertificateRevocationListParams::signed_by()` and providing an issuer + `Certificate` and `KeyPair`. + +* Previously a created `CertificateRevocationList` could be serialized to DER or + PEM by calling `CertificateRevocationList::serialize_der_with_signer()` or + `CertificateRevocationList::serialize_pem_with_signer()`. This is now done by + calling `CertificateRevocationList::der()` or + `CertificateRevocationList::pem()`.