Crate hpke_errors
source · [−]Expand description
HPKE Errors
The high-level, public HPKE APIs specified in this document are all fallible.
These include the Setup functions and all encryption context functions.
For example, Decap() can fail if the encapsulated key enc is invalid,
and Open() may fail if ciphertext decryption fails. The explicit errors
generated throughout this specification, along with the conditions that
lead to each error, are as follows:
ValidationError: KEM input or output validation failure.DeserializeError: Public or private key deserialization failure.EncapError:Encap()failure.DecapError:Decap()failure.OpenError: Context AEADOpen()failure.MessageLimitReachedError: Context AEAD sequence number overflow.DeriveKeyPairError: Key pair derivation failure.
Implicit errors may also occur. As an example, certain classes of failures,
e.g., malformed recipient public keys, may not yield explicit errors.
For example, for the DHKEM variant described in this specification,
the Encap() algorithm fails when given an invalid recipient public key.
However, other KEM algorithms may not have an efficient algorithm for verifying
the validity of public keys. As a result, an equivalent error may not manifest
until AEAD decryption at the recipient. As another example, DHKEM’s AuthDecap()
function will produce invalid output if given the wrong sender public key.
This error is not detectable until subsequent AEAD decryption.
The errors in this document are meant as a guide for implementors. They are not an exhaustive list of all the errors an implementation might emit. For example, future KEMs might have internal failure cases, or an implementation might run out of memory.
How these errors are expressed in an API or handled by applications is an
implementation-specific detail. For example, some implementations may abort or
panic upon a DeriveKeyPairError failure given that it only occurs with
negligible probability, whereas other implementations may retry the failed
DeriveKeyPair operation.
As another example, some implementations of the DHKEM specified in this document
may choose to transform ValidationError from DH() into an EncapError or
DecapError from Encap() or Decap(), respectively, whereas others may choose
to raise ValidationError unmodified.
Applications using HPKE APIs should not assume that the errors here are complete,
nor should they assume certain classes of errors will always manifest the same way
for all ciphersuites. For example, the DHKEM specified in this document will emit
a DeserializationError or ValidationError if a KEM public key is invalid. However,
a new KEM might not have an efficient algorithm for determining whether or not a
public key is valid. In this case, an invalid public key might instead yield an
OpenError when trying to decrypt a ciphertext.
Exceptions
The exceptions raised in the HPKE RFC are modelled as errors here as well:
InconsistentPskInputs: PSK inputs are inconsistent.UnnecessaryPsk: PSK input provided when not needed.MissingPsk: Missing required PSK input.
hacspec Extensions
In order to implement HPKE a number of additional errors are added here:
UnsupportedAlgorithm: An algorithm is not supported by the implementationInvalidParameters: Parameters to an algorithm are inconsistent or wrong.CryptoError: An opaque error happened in a crypto operation outside of this code.
Enums
Explicit errors generated throughout this specification.