identity_storage/key_storage/
key_storage_error.rs

1// Copyright 2020-2023 IOTA Stiftung
2// SPDX-License-Identifier: Apache-2.0
3
4use std::fmt::Display;
5
6use identity_core::common::SingleStructError;
7
8/// Error type for key storage operations.
9pub type KeyStorageError = SingleStructError<KeyStorageErrorKind>;
10
11/// The cause of the failed key storage operation.
12#[derive(Debug, Clone)]
13#[non_exhaustive]
14pub enum KeyStorageErrorKind {
15  /// Indicates that a user tried to generate a key which the key storage implementation
16  /// does not support.
17  UnsupportedKeyType,
18
19  /// Indicates an attempt to generate or insert a key with a key type that the key storage implementation
20  /// deems incompatible with the given signature algorithm.
21  KeyAlgorithmMismatch,
22
23  /// Indicates an attempt to parse a signature algorithm that is not recognized by the key storage implementation.
24  UnsupportedSignatureAlgorithm,
25
26  /// Indicates an attempt to parse a proof algorithm that is not recognized by the key storage implementation.
27  UnsupportedProofAlgorithm,
28
29  /// Indicates that the key storage implementation is not able to find the requested key.
30  KeyNotFound,
31
32  /// Indicates that the storage is unavailable for an unpredictable amount of time.
33  ///
34  /// Occurrences of this variant should hopefully be rare, but could occur if hardware fails, or a hosted key store
35  /// goes offline.
36  Unavailable,
37
38  /// Indicates that an attempt was made to authenticate with the key storage, but the operation did not succeed.
39  Unauthenticated,
40
41  /// Indicates an unsuccessful I/O operation that may be retried, such as a temporary connection failure or timeouts.
42  ///
43  /// Returning this error signals to the caller that the operation may be retried with a chance of success.
44  /// It is at the caller's discretion whether to retry or not, and how often.
45  RetryableIOFailure,
46
47  /// Indicates a failure to serialize or deserialize.
48  SerializationError,
49
50  /// Indicates that something went wrong, but it is unclear whether the reason matches any of the other variants.
51  ///
52  /// When using this variant one may want to attach additional context to the corresponding [`KeyStorageError`]. See
53  /// [`KeyStorageError::with_custom_message`](KeyStorageError::with_custom_message()) and
54  /// [`KeyStorageError::with_source`](KeyStorageError::with_source()).
55  Unspecified,
56}
57
58impl KeyStorageErrorKind {
59  /// Returns the string representation of the error.
60  pub const fn as_str(&self) -> &str {
61    match self {
62      Self::UnsupportedKeyType => "key generation failed: the provided multikey schema is not supported",
63      Self::KeyAlgorithmMismatch => "the key type cannot be used with the algorithm",
64      Self::UnsupportedSignatureAlgorithm => "signing algorithm parsing failed",
65      Self::UnsupportedProofAlgorithm => "proof algorithm parsing failed",
66      Self::KeyNotFound => "key not found in storage",
67      Self::Unavailable => "key storage unavailable",
68      Self::Unauthenticated => "authentication with the key storage failed",
69      Self::Unspecified => "key storage operation failed",
70      Self::RetryableIOFailure => "key storage was unsuccessful because of an I/O failure",
71      Self::SerializationError => "(de)serialization error",
72    }
73  }
74}
75
76impl AsRef<str> for KeyStorageErrorKind {
77  fn as_ref(&self) -> &str {
78    self.as_str()
79  }
80}
81
82impl Display for KeyStorageErrorKind {
83  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
84    write!(f, "{}", self.as_str())
85  }
86}