|
| 1 | +# Rcgen 0.12 to 0.13 Migration Guide |
| 2 | + |
| 3 | +This document is a meant to be a helpful guide for some of the API changes made |
| 4 | +between rcgen 0.12 and 0.13. For information on other changes in 0.13 see |
| 5 | +[rcgen/CHANGELOG.md]. |
| 6 | + |
| 7 | +## Key Pairs |
| 8 | + |
| 9 | +* Previously it was possible to have certificate generation automatically create |
| 10 | + a subject `KeyPair` for you by leaving the `key_pair` field of |
| 11 | + `CertificateParams` empty, and retrieving the generated `KeyPair` from |
| 12 | + a `Certificate` created with the `CertificateParams` by calling |
| 13 | + `Certificate::get_key_pair()`. |
| 14 | + |
| 15 | + To offer more consistency and to keep the `CertificateParams` and `Certificate` |
| 16 | + types from holding private key data, the new API requires you handle `KeyPair` |
| 17 | + creation yourself. See `CertifiedKey`, `KeyPair::generate()`, |
| 18 | + `KeyPair::generate_for()` and `KeyPair::generate_rsa_for()` for more information. |
| 19 | + |
| 20 | +* Serializing a `Certificate`'s `KeyPair` to DER or PEM was previously done by |
| 21 | + calling `Certificate::serialize_private_key_der()` or |
| 22 | + `Certificate::serialize_private_key_pem()`. This is now handled by calling |
| 23 | + `KeyPair::serialize_der()` or `KeyPair::serialize_pem()`. |
| 24 | + |
| 25 | +## Certificates |
| 26 | + |
| 27 | +* For quick-and-easy self-signed certificate issuance, |
| 28 | + `generate_simple_self_signed` now returns a `CertifiedKey` in the success case |
| 29 | + instead of a `Certificate`. The self-signed `Certificate` can be accessed in |
| 30 | + the `cert` field of `CertifiedKey`, and the generated subject key pair in |
| 31 | + `key_pair`. |
| 32 | + |
| 33 | +* Custom self-signed certificate issuance was previously done by |
| 34 | + constructing `CertificateParams` and calling `Certificate::from_params()` to |
| 35 | + create a `Certificate`. This is now done by calling |
| 36 | + `CertificateParams::self_signed()`, providing a subject `KeyPair` of your |
| 37 | + choosing. |
| 38 | + |
| 39 | +* Custom certificate issuance signed by an issuer was previously done by |
| 40 | + constructing `CertificateParams`, calling `Certificate::from_params()` and |
| 41 | + then choosing the issuer at serialization time. This is now done ahead of |
| 42 | + serialization by calling `CertificateParams::signed_by()` and providing |
| 43 | + a subject `KeyPair` as well as an issuer `Certificate` and `KeyPair`. |
| 44 | + |
| 45 | +* Previously certificate serialization was done by calling |
| 46 | + `Certificate::serialize_der()`, `Certificate::serialize_pem()`, |
| 47 | + `Certificate::serialize_der_with_signer()` or |
| 48 | + `Certificate::serialize_pem_with_signer()`. Each time a serialization fn was |
| 49 | + called a new certificate was issued, leading to confusion when it was desired |
| 50 | + to serialize the same certificate in two formats. In the new API issuance is |
| 51 | + handled by `CertificateParams` fns and the generated `Certificate` will not change |
| 52 | + when serialized. You can serialize it to PEM by calling `Certificate::pem()`, |
| 53 | + or access the DER encoding by calling `Certificate::der()`. |
| 54 | + |
| 55 | +## Certificate Signing Requests (CSRs) |
| 56 | + |
| 57 | +* Previously it was only possible to create a new CSR by first issuing |
| 58 | + a `Certificate` from `CertificateParams`, and calling |
| 59 | + `Certificate::serialize_request_pem()` or |
| 60 | + `Certificate::serialize_request_der()`. In the updated API you can create |
| 61 | + a `CertificateSigningRequest` directly from `CertificateParams` by calling |
| 62 | + `CertificateParams::serialize_request` and providing a subject `KeyPair`. You |
| 63 | + may serialize the CSR to DER or PEM by calling |
| 64 | + `CertificateSigningRequest::der()` or `CertificateSingingRequest::pem()`. |
| 65 | + |
| 66 | +* To load a CSR from an existing PEM/DER copy with the old API required |
| 67 | + calling `CertificateSingingRequest::from_pem()` or |
| 68 | + `CertificateSigningRequest::from_der()`. The new API introduces |
| 69 | + a `CertificateSingingRequestParams` type that can be created using |
| 70 | + `CertificateSigningRequestParams::from_pem()` or |
| 71 | + `CertificateSingingRequest::from_der()`. |
| 72 | + |
| 73 | +* To issue a certificate from an existing CSR with the old API required calling |
| 74 | + `CertificateSigningRequest::serialize_der_with_signer()` or |
| 75 | + `CertificateSigningRequest::serialize_pem_with_signer(). In the new API, call |
| 76 | + `CertificateSigningRequestParams::signed_by()` and provide an issuer |
| 77 | + `Certificate` and `KeyPair`. |
| 78 | + |
| 79 | +## Certificate Revocation Lists (CRLs) |
| 80 | + |
| 81 | +* Previously a `CertificateRevocationList` was created by calling |
| 82 | + `CertificateRevocationList::from_params()`. This is now done by calling |
| 83 | + `CertificateRevocationListParams::signed_by()` and providing an issuer |
| 84 | + `Certificate` and `KeyPair`. |
| 85 | + |
| 86 | +* Previously a created `CertificateRevocationList` could be serialized to DER or |
| 87 | + PEM by calling `CertificateRevocationList::serialize_der_with_signer()` or |
| 88 | + `CertificateRevocationList::serialize_pem_with_signer()`. This is now done by |
| 89 | + calling `CertificateRevocationList::der()` or |
| 90 | + `CertificateRevocationList::pem()`. |
0 commit comments