# Revision history for cryptostore

## 0.4.0.0 - 2025-10-12

* Private keys are now represented as type `KeyPair` defined in module
  `Crypto.Store.PKCS8` instead of `PrivKey`.  This ensures that the
  corresponding public key is always available and that the library detects
  and reports data mistakes involving a wrong public key.  A new error
  `PublicPrivateKeyMismatch` is added for that purpose and returned by
  functions `certSigner`, `withRecipientKeyAgree`, `fromCredential` and
  `fromNamedCredential`.  Behavior of functions `toCredential` and
  `toNamedCredential` is now more strict, they return a key and leaf
  certificate that always match.  Functions to convert `KeyPair` to/from the
  usual type `PrivKey` are also exposed from module `Crypto.Store.PKCS8`.

* Added support of PBMAC1 for PKCS#12 integrity.  Type `IntegrityParams` used
  in functions `writeP12File` and `writeP12FileToMemory` is modified.
  A low-level function for PBMAC1 is also available in the PKCS5 module.

* CMS now supports SHA-3 algorithms in HMAC, ECDSA, or as digest algorithm

* Functions `pemToKey`, `pemToPubKey` and `pemToContentInfo` are modified to
  return error details when a PEM object cannot be read.  The old API signature
  that discarded error details is available with functions renamed
  `pemToKeyAccum`, `pemToPubKeyAccum` and `pemToContentInfoAccum`.

* Function `generateEncryptionParams` is removed and can be replaced with
  functions `ecbParams`, `generateCBCParams`, `generateCFBParams` or
  `generateCTRParams` according to the desired mode.

* Functions `generateAuthEnc128Params` and `generateAuthEnc256Params` are
  replaced with `authEnc128Params` and `authEnc256Params`.  The new API expects
  a `ContentEncryptionParams` argument instead of `ContentEncryptionAlg`.

* CMS encrypted data, enveloped data and authenticated-enveloped data now
  support optional HKDF-SHA256 derivation of the content-encryption key.  When
  generating encryption parameters, enable the key derivation feature with a
  call to functions `deriveEncryptionKey` or `authDeriveEncryptionKey`.  The
  feature prevents AEAD-to-CBC downgrade attack scenarios for `CCM` and `GCM`
  modes but requires support from the receiving end.

* Fixed encoding of some HMAC and PRF parameters

## 0.3.1.0 - 2024-05-05

* Strict validation of GCM/CCM authentication tag length

## 0.3.0.1 - 2023-06-25

* Add optional flag to use crypton instead of cryptonite

## 0.3.0.0 - 2023-01-14

* API change in PKCS5, PKCS8 and PKCS12 modules to handle better password-based
  encryption derived from an empty password.  All encryption/decryption
  functions now expect an opaque `ProtectionPassword` data type.  Conversion
  functions `toProtectionPassword` and `fromProtectionPassword` are provided.
  Additionnally in the PKCS12 module, the type `OptProtected` is replaced with
  `OptAuthenticated` when dealing with password integrity.  Similarly at that
  level, function `recover` is to be replaced with `recoverAuthenticated`.

* Added support for KMAC (Keccak Message Authentication Code) in CMS
  authenticated data, through constructors `KMAC_SHAKE128` and `KMAC_SHAKE256`.

* CMS key agreement now supports derivation with HKDF along with X9.63.  Data
  type `KeyAgreementParams` is modified to include a KDF instead of simply the
  digest algorithm.  HKDF has assigned OIDs only for standard DH and cannot be
  used with cofactor DH.

* Added CMS utility functions to deal with the `signingTime` attribute.

* Changed `withSignerCertificate` validation callback API to include the
  `signingTime` value when available.

## 0.2.3.0 - 2022-11-05

* Fix RC2 on big-endian architectures

## 0.2.2.0 - 2022-04-16

* Fix buffer overrun in `pkcs12Derive`

## 0.2.1.0 - 2019-10-13

* Added CMS fuctions `contentInfoToDER` and `berToContentInfo` in order to
  generate and parse raw ASN.1.

* Implementation of AES key wrap had some optimizations.

* SHAKE hash algorithms now allow arbitrary output lengths.  Lengths that are
  very small decrease security.  A protection is added so that attempts to use
  lengths which are too small fail, although the criteria are conservative.
  Generating and parsing content has no restriction.

## 0.2.0.0 - 2019-03-24

* Added functions `toNamedCredential` and `fromNamedCredential` to handle
  PKCS#12 elements with an alias (friendly name).

* Functions `fromCredential` and `fromNamedCredential` now generate PKCS#12
  elements with the `localKeyId` attribute.

* Function `toCredential` is now able to locate the leaf certificate and issuers
  more reliably.

* Algorithms X25519, X448, Ed25519 and Ed448 are now supported.

* CMS functions `digestVerify` and `verifySignedData` now return an `Either`
  instead of a `Maybe`.  Errors `DigestMismatch` and `SignatureNotVerified` are
  added to report failures.

* CMS types `SignedData`, `DigestedData` and `AuthenticatedData` now retain the
  encapsulated content in encoded form (with type alias `EncapsulatedContent`)
  instead of a decoded and parsed `ContentInfo`.  The `ContentInfo` is parsed
  and provided only when successfully unwrapping the encapsulated type.

* The CMS interface is transformed to support detached content.  CMS types now
  have a type parameter to distinguish between a direct reference to the
  encapsulated or encrypted content, and the `Encap` indirection which denotes
  an attached or detached content.  Functions building CMS types do not return
  the `ContentInfo` directly anymore, but an intermediate type to be fed into
  `toAttachedCI` or `toDetachedCI`.  Reverse transformation is possible with
  utility functions `fromAttached` and `fromDetached` when unwrapping a
  `ContentInfo`.

## 0.1.0.0 - 2018-09-23

* First version. Released on an unsuspecting world.