From e44e2c0d31f448bc65e296f41b681bbd7f3b2840 Mon Sep 17 00:00:00 2001 From: OnkelDe <84448649+OnkelDe@users.noreply.github.com> Date: Wed, 19 Jun 2024 10:10:53 +0200 Subject: [PATCH] Update categories.md --- docs/_pages/categories.md | 468 +++++++++++++++++++++++++++++++++++++- 1 file changed, 464 insertions(+), 4 deletions(-) diff --git a/docs/_pages/categories.md b/docs/_pages/categories.md index 540268d..8f6647c 100644 --- a/docs/_pages/categories.md +++ b/docs/_pages/categories.md @@ -57,10 +57,6 @@ Conduct a thorough risk assessment of the implemented key management system to i - - - - ## Crypto Layer The Crypto Layer is a comprehensive and flexible cryptographic library designed to provide a unified interface for various cryptographic operations and algorithms. It offers a wide range of functionalities, including encryption, decryption, signing, signature verification, and hashing, while supporting both symmetric and asymmetric cryptography. @@ -218,6 +214,470 @@ Contributions to the Crypto Layer are welcome! If you find any issues or have su The Crypto Layer is released under the [MIT License](LICENSE). +# YubiKey Provider Documentation + +## Overview + +This module provides cryptographic operations using a YubiKey. It implements the `Provider` trait and interacts with the YubiKey device for key management and cryptographic operations. + +## Table of Contents + +1. [Dependencies](#dependencies) +2. [Constants](#constants) +3. [Provider Implementation](#provider-implementation) + - [create_key](#create_key) + - [load_key](#load_key) + - [initialize_module](#initialize_module) +4. [Helper Functions](#helper-functions) + - [save_key_object](#save_key_object) + - [parse_slot_data](#parse_slot_data) + - [get_free_slot](#get_free_slot) + - [get_reference_u32slot](#get_reference_u32slot) + - [list_all_slots](#list_all_slots) +5. [License](#license) + + +# YubiKey Provider Documentation + +## Overview + +This module provides cryptographic operations using a YubiKey. It implements the `Provider` trait and interacts with the YubiKey device for key management and cryptographic operations. + +## Table of Contents + +1. [Dependencies](#dependencies) +2. [Constants](#constants) +3. [Provider Implementation](#provider-implementation) + - [create_key](#create_key) + - [load_key](#load_key) + - [initialize_module](#initialize_module) +4. [Helper Functions](#helper-functions) + - [save_key_object](#save_key_object) + - [parse_slot_data](#parse_slot_data) + - [get_free_slot](#get_free_slot) + - [get_reference_u32slot](#get_reference_u32slot) + - [list_all_slots](#list_all_slots) +5. [License](#license) + +## Dependencies + +```rust +use super::YubiKeyProvider; +use crate::common::{ + crypto::algorithms::{ + encryption::{AsymmetricEncryption, EccCurves, EccSchemeAlgorithm}, + KeyBits, + }, + error::SecurityModuleError, + traits::module_provider::Provider, +}; +use crate::hsm::{core::error::HsmError, HsmProviderConfig}; +use ::yubikey::{ + piv::{self, AlgorithmId, RetiredSlotId, SlotId}, + Error, YubiKey, +}; +use base64::{engine::general_purpose, Engine}; +use std::any::Any; +use std::sync::{Arc, Mutex}; +use tracing::instrument; +use x509_cert::der::Encode; +use yubikey::MgmKey; +Constants +SLOTS +rust +Code kopieren +const SLOTS: [RetiredSlotId; 20] = [ + RetiredSlotId::R1, + RetiredSlotId::R2, + // ... remaining slots + RetiredSlotId::R20, +]; +SLOTSU32 +rust +Code kopieren +const SLOTSU32: [u32; 20] = [ + 0x005f_c10d, + // ... remaining slots + 0x005f_c120, +]; +Provider Implementation +create_key +Creates a new cryptographic key identified by the provider-given key_id. + +Arguments +key_id: A string slice that uniquely identifies the key. +config: A boxed ProviderConfig containing configuration details for key generation. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +#[instrument] +fn create_key( + &mut self, + key_id: &str, + config: Box, +) -> Result<(), SecurityModuleError> { + // Implementation here +} +load_key +Loads an existing cryptographic key identified by key_id. + +Arguments +key_id: A string slice that uniquely identifies the key. +config: A boxed ProviderConfig containing configuration details. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +#[instrument] +fn load_key(&mut self, key_id: &str, config: Box) -> Result<(), SecurityModuleError> { + // Implementation here +} +initialize_module +Initializes the YubiKey module and returns a handle for cryptographic operations. + +Arguments +key_algorithm: The asymmetric encryption algorithm to be used for the key. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a Yubikey based Error. + +Example +rust +Code kopieren +#[instrument] +fn initialize_module(&mut self) -> Result<(), SecurityModuleError> { + // Implementation here +} +Helper Functions +save_key_object +Saves the key object to the YubiKey device. + +Arguments +yubikey: Reference to the YubiKey device. +key_id: A string slice that uniquely identifies the key. +slot_id: An address where an object will be stored. +pkey: The public key which is intended to be stored. +algo: Algorithm identifier. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a yubikey::Error. + +Example +rust +Code kopieren +fn save_key_object( + yubikey: &mut YubiKey, + key_id: &str, + slot_id: u32, + pkey: &str, + algo: &str, +) -> Result<(), yubikey::Error> { + // Implementation here +} +parse_slot_data +Parses the data from a YubiKey slot. + +Arguments +data: Reference to the data array. +Returns +A Result that, on success, contains Ok((key_name, slot, public_key, algo)). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn parse_slot_data(data: &[u8]) -> Result<(String, String, String, String), SecurityModuleError> { + // Implementation here +} +get_free_slot +Gets a free slot for storing a key object. + +Arguments +yubikey: Reference to the YubiKey device. +Returns +A Result that, on success, contains Ok(RetiredSlotId). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn get_free_slot(yubikey: &mut YubiKey) -> Result { + // Implementation here +} +get_reference_u32slot +Converts a RetiredSlotId to its corresponding u32 value. + +Arguments +slot: The RetiredSlotId to be converted. +Returns +The corresponding u32 value of the RetiredSlotId. + +Example +rust +Code kopieren +fn get_reference_u32slot(slot: RetiredSlotId) -> u32 { + // Implementation here +} +list_all_slots +Lists all slots with their corresponding key information. + +Arguments +yubikey: Reference to the YubiKey device. +Returns +A Result that, on success, contains Ok(Vec) with information about all slots. On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn list_all_slots(yubikey: &mut YubiKey) -> Result, SecurityModuleError> { + // Implementation here +} +License +This project is licensed under the MIT License - see the LICENSE file for details. + +sql +Code kopieren + +You can copy and paste the above content directly into your Markdown file for your GitHub Pages. +put everything in md file + +ChatGPT +Sure, here is everything put together in a single Markdown file: + +markdown +Code kopieren +# YubiKey Provider Documentation + +## Overview + +This module provides cryptographic operations using a YubiKey. It implements the `Provider` trait and interacts with the YubiKey device for key management and cryptographic operations. + +## Table of Contents + +1. [Dependencies](#dependencies) +2. [Constants](#constants) +3. [Provider Implementation](#provider-implementation) + - [create_key](#create_key) + - [load_key](#load_key) + - [initialize_module](#initialize_module) +4. [Helper Functions](#helper-functions) + - [save_key_object](#save_key_object) + - [parse_slot_data](#parse_slot_data) + - [get_free_slot](#get_free_slot) + - [get_reference_u32slot](#get_reference_u32slot) + - [list_all_slots](#list_all_slots) +5. [License](#license) + +## Dependencies + +```rust +use super::YubiKeyProvider; +use crate::common::{ + crypto::algorithms::{ + encryption::{AsymmetricEncryption, EccCurves, EccSchemeAlgorithm}, + KeyBits, + }, + error::SecurityModuleError, + traits::module_provider::Provider, +}; +use crate::hsm::{core::error::HsmError, HsmProviderConfig}; +use ::yubikey::{ + piv::{self, AlgorithmId, RetiredSlotId, SlotId}, + Error, YubiKey, +}; +use base64::{engine::general_purpose, Engine}; +use std::any::Any; +use std::sync::{Arc, Mutex}; +use tracing::instrument; +use x509_cert::der::Encode; +use yubikey::MgmKey; +Constants +SLOTS +rust +Code kopieren +const SLOTS: [RetiredSlotId; 20] = [ + RetiredSlotId::R1, + RetiredSlotId::R2, + RetiredSlotId::R3, + RetiredSlotId::R4, + RetiredSlotId::R5, + RetiredSlotId::R6, + RetiredSlotId::R7, + RetiredSlotId::R8, + RetiredSlotId::R9, + RetiredSlotId::R10, + RetiredSlotId::R11, + RetiredSlotId::R12, + RetiredSlotId::R13, + RetiredSlotId::R14, + RetiredSlotId::R15, + RetiredSlotId::R16, + RetiredSlotId::R17, + RetiredSlotId::R18, + RetiredSlotId::R19, + RetiredSlotId::R20, +]; +SLOTSU32 +rust +Code kopieren +const SLOTSU32: [u32; 20] = [ + 0x005f_c10d, + 0x005f_c10e, + 0x005f_c10f, + 0x005f_c110, + 0x005f_c111, + 0x005f_c112, + 0x005f_c113, + 0x005f_c114, + 0x005f_c115, + 0x005f_c116, + 0x005f_c117, + 0x005f_c118, + 0x005f_c119, + 0x005f_c11a, + 0x005f_c11b, + 0x005f_c11c, + 0x005f_c11d, + 0x005f_c11e, + 0x005f_c11f, + 0x005f_c120, +]; +Provider Implementation +create_key +Creates a new cryptographic key identified by the provider-given key_id. + +Arguments +key_id: A string slice that uniquely identifies the key. +config: A boxed ProviderConfig containing configuration details for key generation. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +#[instrument] +fn create_key( + &mut self, + key_id: &str, + config: Box, +) -> Result<(), SecurityModuleError> { + // Implementation here +} +load_key +Loads an existing cryptographic key identified by key_id. + +Arguments +key_id: A string slice that uniquely identifies the key. +config: A boxed ProviderConfig containing configuration details. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +#[instrument] +fn load_key(&mut self, key_id: &str, config: Box) -> Result<(), SecurityModuleError> { + // Implementation here +} +initialize_module +Initializes the YubiKey module and returns a handle for cryptographic operations. + +Arguments +key_algorithm: The asymmetric encryption algorithm to be used for the key. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a Yubikey based Error. + +Example +rust +Code kopieren +#[instrument] +fn initialize_module(&mut self) -> Result<(), SecurityModuleError> { + // Implementation here +} +Helper Functions +save_key_object +Saves the key object to the YubiKey device. + +Arguments +yubikey: Reference to the YubiKey device. +key_id: A string slice that uniquely identifies the key. +slot_id: An address where an object will be stored. +pkey: The public key which is intended to be stored. +algo: Algorithm identifier. +Returns +A Result that, on success, contains Ok(()). On failure, it returns a yubikey::Error. + +Example +rust +Code kopieren +fn save_key_object( + yubikey: &mut YubiKey, + key_id: &str, + slot_id: u32, + pkey: &str, + algo: &str, +) -> Result<(), yubikey::Error> { + // Implementation here +} +parse_slot_data +Parses the data from a YubiKey slot. + +Arguments +data: Reference to the data array. +Returns +A Result that, on success, contains Ok((key_name, slot, public_key, algo)). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn parse_slot_data(data: &[u8]) -> Result<(String, String, String, String), SecurityModuleError> { + // Implementation here +} +get_free_slot +Gets a free slot for storing a key object. + +Arguments +yubikey: Reference to the YubiKey device. +Returns +A Result that, on success, contains Ok(RetiredSlotId). On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn get_free_slot(yubikey: &mut YubiKey) -> Result { + // Implementation here +} +get_reference_u32slot +Converts a RetiredSlotId to its corresponding u32 value. + +Arguments +slot: The RetiredSlotId to be converted. +Returns +The corresponding u32 value of the RetiredSlotId. + +Example +rust +Code kopieren +fn get_reference_u32slot(slot: RetiredSlotId) -> u32 { + // Implementation here +} +list_all_slots +Lists all slots with their corresponding key information. + +Arguments +yubikey: Reference to the YubiKey device. +Returns +A Result that, on success, contains Ok(Vec) with information about all slots. On failure, it returns a SecurityModuleError. + +Example +rust +Code kopieren +fn list_all_slots(yubikey: &mut YubiKey) -> Result, SecurityModuleError> { + // Implementation here +} + + thematical operations. Transport Layer Security (TLS): TLS is a protocol for encrypting connections at the transport layer, which can be used to secure the connection itself, while OpenPGP encrypts the data within that connection.