docs: update CHANGELOG for 0.13.0

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

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()`.