Constants and Enums
Overview
The keychain library provides a comprehensive set of constants and enumerations that define cryptographic algorithms, data types, security levels, and protocol parameters. All enum classes inherit from IntEnum
to ensure compatibility with the underlying C library.
Package: keychain.constants
from keychain.constants import (
SecurityLevel,
DataType,
KeychainType,
ConsensusAlgorithm,
EncryptionScheme,
SignatureScheme,
# ... and many more
)
Security and Configuration
SecurityLevel
class SecurityLevel(IntEnum):
"""Persona security level for key generation and rollovers."""
Defines security levels that determine cryptographic parameters for key generation:
Values:
-
UNKNOWN_LEVEL = 0
- Unknown security level -
LIGHTWEIGHT = 1
- Transient crypto period (weeks/months), very low risk -
LOW = 2
- Up to 2 year crypto period, low risk -
MEDIUM = 3
- Up to 5 year crypto period, moderate risk -
HIGH = 4
- Up to 10 year crypto period, high risk -
ULTRA = 5
- 10+ year crypto period, very high risk
Example:
from keychain.constants import SecurityLevel
# Set security level for persona creation
security_level = SecurityLevel.HIGH
print(f"Security level: {security_level.name} ({security_level.value})")
SerializationFormat
class SerializationFormat(IntEnum):
"""String serialization format."""
Defines available serialization formats:
Values:
-
XML = 1
- XML format (deprecated as of 3.0) -
PROTOBUF = 2
- Protocol Buffers format (default) -
JSON = 3
- JSON format (coming soon)
CharEncoding
class CharEncoding(IntEnum):
"""Character encoding of data."""
Extensive character encoding support including:
Primary Encodings:
-
UTF8 = 1
- UTF-8 encoding -
UTF16 = 2
- UTF-16 encoding -
UTF32 = 5
- UTF-32 encoding -
BINARY = 3
- Binary data (no character encoding) -
US_ASCII = 6
- US ASCII encoding
ISO Encodings:
-
ISO_8859_1
throughISO_8859_10
- Various ISO 8859 encodings -
ISO_8859_6_E
,ISO_8859_6_I
,ISO_8859_8_E
,ISO_8859_8_I
- Extended ISO variants
Asian Encodings:
-
SHIFT_JIS = 17
- Shift JIS (Japanese) -
EUC_JP = 18
- EUC-JP (Japanese) -
EUC_KR = 20
- EUC-KR (Korean) -
ISO_2022_JP = 21
,ISO_2022_KR = 19
- ISO 2022 variants -
GB2312 = 27
- GB 2312 (Chinese) -
BIG5 = 28
- Big5 (Chinese)
Other Encodings:
-
KOI8_R = 29
- KOI8-R (Russian) -
OTHER_TEXT = 4
- Other text encoding not listed
Data Types
DataType
class DataType(IntEnum):
"""Data type metadata for serialized data."""
Comprehensive data type system supporting primitive types, complex objects, and arrays:
Primitive Types:
-
BYTES = 0
- Binary byte array -
UTF8_STRING = 1
- UTF-8 string -
INT32 = 2
,INT64 = 3
- Signed integers -
UINT32 = 4
,UINT64 = 5
- Unsigned integers -
BOOLEAN = 6
- Boolean value -
SINGLE_FLOAT = 12
,DOUBLE_FLOAT = 13
- Floating point numbers
Complex Types:
-
DID = 7
- Decentralized Identifier -
VERIFIABLE_DATA = 8
- Verifiable data object -
CREDENTIAL = 9
- W3C credential -
TRANSACTION = 10
- Ledger transaction -
ENCRYPTED_DATA = 11
- Encrypted data -
KEY_LOCK = 30
- Key lock object -
ATTESTATION = 31
- Attestation -
PUBLIC_KEY = 34
- Public key -
SERIALIZABLE = 36
- Generic serializable object
Array Types:
All primitive and complex types have corresponding array variants (e.g., ARRAY_BYTES = 15
, ARRAY_DID = 22
, etc.)
Example:
from keychain.constants import DataType
# Check data types
if data.data_type() == DataType.CREDENTIAL:
print("This is a credential")
elif data.data_type() == DataType.ARRAY_DID:
print("This is an array of DIDs")
Cryptographic Algorithms
Encryption Algorithms
EncryptionAlgorithmClass
class EncryptionAlgorithmClass(IntEnum):
"""Encryption algorithm class."""
Values:
-
ECIES = 1
- Elliptic Curve Integrated Encryption Scheme -
RSA = 2
- RSA Encryption Scheme -
DLIES = 3
- Discrete Logarithm Integrated Encryption Scheme -
ELGAMAL = 4
- ElGamal Integrated Encryption Scheme
EncryptionScheme
class EncryptionScheme(IntEnum):
"""Specific public-key encryption algorithms."""
ECIES Variants:
-
ECIES_ECP_SECP160R1 = 1
- 160-bit curve -
ECIES_ECP_SECP192K1 = 2
- 192-bit curve -
ECIES_ECP_SECP224R1 = 3
- 224-bit curve -
ECIES_ECP_SECP256R1 = 4
- 256-bit curve -
ECIES_ECP_SECP384R1 = 5
- 384-bit curve -
ECIES_ECP_SECP521R1 = 6
- 521-bit curve
RSA Variants:
-
RSA_OAEP_SHA_1024 = 7
- 1024-bit RSA with OAEP -
RSA_OAEP_SHA_2048 = 8
- 2048-bit RSA with OAEP -
RSA_OAEP_SHA_3072 = 9
- 3072-bit RSA with OAEP -
RSA_OAEP_SHA_4096 = 10
- 4096-bit RSA with OAEP
DLIES Variants:
-
DLIES_1024 = 11
throughDLIES_4096 = 14
- Various key sizes
ElGamal Variants:
-
ELGAMAL_1024 = 15
throughELGAMAL_4096 = 18
- Various key sizes
Signature Algorithms
SignatureAlgorithmClass
class SignatureAlgorithmClass(IntEnum):
"""Public-key signing algorithm class."""
Values:
-
ECDSA = 1
- Elliptic Curve Digital Signature Algorithm -
ECGDSA = 2
- German Elliptic Curve Digital Signature Algorithm -
RSASS = 3
- RSA Probabilistic Signature Scheme -
DSA = 4
- Digital Signature Algorithm
SignatureScheme
class SignatureScheme(IntEnum):
"""Specific public-key signing algorithms."""
ECDSA Variants:
-
ECDSA_ECP_SECP112R2 = 150
- 112-bit curve -
ECDSA_ECP_SECP128R1 = 149
- 128-bit curve -
ECDSA_ECP_SECP160R1 = 129
- 160-bit curve -
ECDSA_ECP_SECP192K1 = 130
- 192-bit curve -
ECDSA_ECP_SECP224R1 = 131
- 224-bit curve -
ECDSA_ECP_SECP256R1 = 132
- 256-bit curve -
ECDSA_ECP_SECP384R1 = 133
- 384-bit curve -
ECDSA_ECP_SECP521R1 = 134
- 521-bit curve
ECGDSA Variants:
-
ECGDSA_ECP_SECP112R2 = 152
throughECGDSA_ECP_SECP521R1 = 140
- Various curves
RSASS Variants:
-
RSASS_PSS_1024 = 141
throughRSASS_PSS_4096 = 144
- Various key sizes
DSA Variants:
-
DSA_1024 = 145
throughDSA_4096 = 148
- Various key sizes
Symmetric Cryptography
CipherClass
class CipherClass(IntEnum):
"""Symmetric cipher class."""
Values:
-
AES = 1
- Advanced Encryption Standard -
CAMELIA = 2
- Camellia block cipher
Cipher
class Cipher(IntEnum):
"""Specific symmetric cipher algorithms."""
AES Variants:
-
AES_GCM_128 = 1
- AES-GCM with 128-bit key -
AES_GCM_192 = 2
- AES-GCM with 192-bit key -
AES_GCM_256 = 3
- AES-GCM with 256-bit key
Camellia Variants:
-
CAMELLIA_GCM_128 = 4
- Camellia-GCM with 128-bit key -
CAMELLIA_GCM_192 = 5
- Camellia-GCM with 192-bit key -
CAMELLIA_GCM_256 = 6
- Camellia-GCM with 256-bit key
Keychain and Identity
KeychainType
class KeychainType(IntEnum):
"""Keychain type (encrypt or sign)."""
Values:
-
ENCRYPT = 0
- Encryption keychain -
SIGN = 1
- Signature keychain
Example:
from keychain.constants import KeychainType
# Create different keychain types
encrypt_keychain = create_keychain(KeychainType.ENCRYPT)
sign_keychain = create_keychain(KeychainType.SIGN)
KeyIdType
class KeyIdType(IntEnum):
"""How a public key is represented in verifiable and encrypted data."""
Values:
-
PUBLIC_KEY = 0
- Full public key is provided -
PUBLIC_KEY_HASH = 1
- Hash of the public key is provided -
TXID_VOUT = 2
- Bitcoin transaction ID/output (deprecated)
DidStatus
class DidStatus(IntEnum):
"""DID lifecycle status tracked in the database."""
Values:
-
UNINITIALIZED = 0
- Yet uninitialized state -
CREATED = 1
- Key pair created and stored -
FUNDING = 2
- Acquiring resources for broadcasting -
BROADCASTED = 3
- Self-signed certificate broadcasted -
CONFIRMING = 4
- Confirmation in progress -
CONFIRMED = 5
- Certificate confirmed (mature persona) -
EXPIRING = 6
- Certificate expiration imminent -
EXPIRED = 7
- Certificate has expired
Consensus and Ledger
ConsensusAlgorithm
class ConsensusAlgorithm(IntEnum):
"""Consensus algorithm used in ledger protocols."""
Values:
-
UNINITIALIZED = 0
- No algorithm specified -
ONE_PHASE_COMMIT = 1
- Single-phase commit -
TWO_PHASE_COMMIT = 2
- Two-phase commit (Propose/Commit) -
THREE_PHASE_COMMIT = 3
- Three-phase commit (Propose/PreCommit/Commit)
Example:
from keychain.constants import ConsensusAlgorithm
# Set consensus algorithm
consensus = ConsensusAlgorithm.THREE_PHASE_COMMIT
print(f"Using {consensus.name} consensus")
ConsensusStage
class ConsensusStage(IntEnum):
"""Stage of a consensus protocol."""
Values:
-
PROPOSE = 1
- Propose application state -
PRECOMMIT = 2
- Pre-commitment attestations -
COMMIT = 3
- Final commitment attestations -
REJECTED = 4
- Transaction rejected
LedgerResult
class LedgerResult(IntEnum):
"""Ledger-state evaluation result during consensus."""
Values:
-
NO_RESPONSE_NEEDED = 0
- No response required -
RESPONSE_NEEDED = 1
- Response should be sent -
PROTOCOL_LEVEL_REJECTED = 2
- Protocol rejection, send transaction -
APPLICATION_LEVEL_REJECTED = 3
- Application rejection, don’t send
Version
class Version(IntEnum):
"""Version numbers for data formats and schemas."""
Values:
-
UNINITIALIZED_VERSION = 0
- Uninitialized -
V20190716 = 1
- Version from July 16, 2019 -
V20200304 = 2
- Version from March 4, 2020 -
V20220412 = 3
- Version from April 12, 2022 -
V20230102 = 4
- Version from January 2, 2023 -
V20240412 = 5
- Version from April 12, 2024 (Herbie Hancock’s birthday)
Configuration Constants
Library Configuration
# Library paths
DEFAULT_LIBRARY_PATH: Final[str] = "~/.local/lib/libkeychain.so"
LIBRARY_SEARCH_PATHS: Final[List[str]] = [
"~/.local/lib/libkeychain.so",
"/usr/local/lib/libkeychain.so",
"/usr/lib/libkeychain.so",
"./libkeychain.so"
]
Default Values
# Security and serialization defaults
DEFAULT_SECURITY_LEVEL: Final[SecurityLevel] = SecurityLevel.MEDIUM
DEFAULT_SERIALIZATION_FORMAT: Final[SerializationFormat] = SerializationFormat.PROTOBUF
Protocol Constants
# Protocol identifiers
PROTOCOL_DOMAIN: Final[str] = "KC"
QUORUM_MEMBERS: Final[str] = "Members"
CONSENSUS_STAGE_TAG: Final[str] = "CS"
Confirmation and Timing
# Confirmation depths
WEAK_DEPTH: Final[int] = 1
STRONG_DEPTH: Final[int] = 3
CERTIFICATE_EXPIRATION_BLOCKS: Final[int] = 5000
Example: Using Constants and Enums
from keychain.constants import (
SecurityLevel,
KeychainType,
ConsensusAlgorithm,
EncryptionScheme,
SignatureScheme,
DEFAULT_SECURITY_LEVEL,
STRONG_DEPTH
)
from keychain.core.gateway import Gateway
def create_secure_persona():
"""Create a persona with high security settings."""
gateway = Gateway()
# Use high security level
security_level = SecurityLevel.HIGH
print(f"Creating persona with {security_level.name} security")
# Create persona with custom settings
persona = gateway.create_persona(
name="secure_persona",
security_level=security_level
)
return persona
def setup_consensus_transaction():
"""Setup a transaction with three-phase commit consensus."""
# Configure consensus algorithm
consensus_algo = ConsensusAlgorithm.THREE_PHASE_COMMIT
print(f"Using {consensus_algo.name} consensus algorithm")
# Transaction setup with consensus
transaction_config = {
"consensus_algorithm": consensus_algo,
"confirmation_depth": STRONG_DEPTH
}
return transaction_config
def compare_crypto_algorithms():
"""Compare different cryptographic algorithm options."""
# Available encryption schemes
encryption_options = [
EncryptionScheme.ECIES_ECP_SECP256R1,
EncryptionScheme.RSA_OAEP_SHA_2048,
EncryptionScheme.ECIES_ECP_SECP384R1
]
# Available signature schemes
signature_options = [
SignatureScheme.ECDSA_ECP_SECP256R1,
SignatureScheme.RSASS_PSS_2048,
SignatureScheme.ECDSA_ECP_SECP384R1
]
print("Encryption Options:")
for scheme in encryption_options:
print(f" {scheme.name} (value: {scheme.value})")
print("\\nSignature Options:")
for scheme in signature_options:
print(f" {scheme.name} (value: {scheme.value})")
def check_data_types(data_objects):
"""Check and categorize different data types."""
for obj in data_objects:
data_type = obj.data_type()
if data_type == DataType.CREDENTIAL:
print(f"Found credential: {obj}")
elif data_type == DataType.DID:
print(f"Found DID: {obj}")
elif data_type == DataType.TRANSACTION:
print(f"Found transaction: {obj}")
elif data_type.name.startswith("ARRAY_"):
print(f"Found array of {data_type.name[6:].lower()}: {obj}")
else:
print(f"Found {data_type.name.lower()}: {obj}")
def demonstrate_keychain_types():
"""Demonstrate different keychain types."""
# Create different keychain types
for keychain_type in KeychainType:
print(f"Creating {keychain_type.name.lower()} keychain")
# Keychain type determines purpose
if keychain_type == KeychainType.ENCRYPT:
print(" - Used for encryption operations")
elif keychain_type == KeychainType.SIGN:
print(" - Used for signature operations")
# Usage examples
if __name__ == "__main__":
print("=== Keychain Constants and Enums Demo ===\\n")
# Default values
print(f"Default security level: {DEFAULT_SECURITY_LEVEL.name}")
print(f"Strong confirmation depth: {STRONG_DEPTH} blocks\\n")
# Create secure persona
persona = create_secure_persona()
print()
# Setup consensus
config = setup_consensus_transaction()
print(f"Transaction config: {config}\\n")
# Compare algorithms
compare_crypto_algorithms()
print()
# Demonstrate keychain types
demonstrate_keychain_types()
Example: Algorithm Selection
from keychain.constants import (
SecurityLevel,
EncryptionScheme,
SignatureScheme,
CipherClass,
Cipher
)
class CryptographicProfile:
"""Cryptographic algorithm profile for different security needs."""
def __init__(self, security_level: SecurityLevel):
self.security_level = security_level
self.encryption_scheme = self._select_encryption_scheme()
self.signature_scheme = self._select_signature_scheme()
self.cipher = self._select_cipher()
def _select_encryption_scheme(self) -> EncryptionScheme:
"""Select encryption scheme based on security level."""
if self.security_level <= SecurityLevel.LOW:
return EncryptionScheme.ECIES_ECP_SECP256R1
elif self.security_level == SecurityLevel.MEDIUM:
return EncryptionScheme.ECIES_ECP_SECP384R1
elif self.security_level == SecurityLevel.HIGH:
return EncryptionScheme.ECIES_ECP_SECP521R1
else: # ULTRA
return EncryptionScheme.RSA_OAEP_SHA_4096
def _select_signature_scheme(self) -> SignatureScheme:
"""Select signature scheme based on security level."""
if self.security_level <= SecurityLevel.LOW:
return SignatureScheme.ECDSA_ECP_SECP256R1
elif self.security_level == SecurityLevel.MEDIUM:
return SignatureScheme.ECDSA_ECP_SECP384R1
elif self.security_level == SecurityLevel.HIGH:
return SignatureScheme.ECDSA_ECP_SECP521R1
else: # ULTRA
return SignatureScheme.RSASS_PSS_4096
def _select_cipher(self) -> Cipher:
"""Select symmetric cipher based on security level."""
if self.security_level <= SecurityLevel.MEDIUM:
return Cipher.AES_GCM_256
else:
return Cipher.CAMELLIA_GCM_256
def get_profile_summary(self) -> dict:
"""Get a summary of the cryptographic profile."""
return {
"security_level": self.security_level.name,
"encryption": self.encryption_scheme.name,
"signature": self.signature_scheme.name,
"symmetric_cipher": self.cipher.name
}
# Usage example
def create_security_profiles():
"""Create cryptographic profiles for different security levels."""
profiles = {}
for level in SecurityLevel:
if level == SecurityLevel.UNKNOWN_LEVEL:
continue
profile = CryptographicProfile(level)
profiles[level.name] = profile.get_profile_summary()
return profiles
# Demonstrate security profiles
profiles = create_security_profiles()
for level_name, profile in profiles.items():
print(f"\\n{level_name} Security Profile:")
for key, value in profile.items():
print(f" {key}: {value}")
See Also
-
Gateway Class - Uses security levels and algorithms
-
Persona Class - Uses keychain types and security levels
-
Credential Class - Uses data types and consensus algorithms
-
DID Classes - Uses DID status and keychain types
-
Transaction Class - Uses consensus algorithms and stages
-
Exception Classes - Error handling for invalid enum values