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