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}