diff --git a/.editorconfig b/.editorconfig index 68c525a..3cc693c 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,37 +1,299 @@ +# EditorConfig is awesome: https://EditorConfig.org + +# top-most EditorConfig file root = true # All files [*] charset = utf-8 -end_of_line = crlf insert_final_newline = true trim_trailing_whitespace = true +end_of_line = lf -# C# files -[*.cs] -indent_style = space +# Code files +[*.{cs,csx,vb,vbx}] indent_size = 4 +indent_style = space +tab_width = 4 -# MSBuild project files +# XML project files [*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}] -indent_style = space indent_size = 2 +indent_style = space -# XML project files +# XML config files [*.{props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}] -indent_style = space indent_size = 2 +indent_style = space # JSON files [*.json] -indent_style = space indent_size = 2 +indent_style = space # YAML files [*.{yml,yaml}] -indent_style = space indent_size = 2 +indent_style = space # Markdown files [*.md] -trim_trailing_whitespace = false \ No newline at end of file +trim_trailing_whitespace = false + +# Shell scripts +[*.sh] +end_of_line = lf + +# Batch files +[*.{cmd,bat}] +end_of_line = crlf + +# C# files +[*.cs] + +#### Core EditorConfig Options #### + +# Indentation and spacing +indent_size = 4 +indent_style = space +tab_width = 4 + +# New line preferences +end_of_line = lf +insert_final_newline = true + +#### .NET Coding Conventions #### + +# Organize usings +dotnet_separate_import_directive_groups = false +dotnet_sort_system_directives_first = true +file_header_template = unset + +# this. and Me. preferences +dotnet_style_qualification_for_event = false:warning +dotnet_style_qualification_for_field = false:warning +dotnet_style_qualification_for_method = false:warning +dotnet_style_qualification_for_property = false:warning + +# Language keywords vs BCL types preferences +dotnet_style_predefined_type_for_locals_parameters_members = true:warning +dotnet_style_predefined_type_for_member_access = true:warning + +# Parentheses preferences +dotnet_style_parentheses_in_arithmetic_binary_operators = always_for_clarity:suggestion +dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:suggestion +dotnet_style_parentheses_in_other_operators = never_if_unnecessary:suggestion +dotnet_style_parentheses_in_relational_binary_operators = always_for_clarity:suggestion + +# Modifier preferences +dotnet_style_require_accessibility_modifiers = for_non_interface_members:warning + +# Expression-level preferences +dotnet_style_coalesce_expression = true:suggestion +dotnet_style_collection_initializer = true:suggestion +dotnet_style_explicit_tuple_names = true:suggestion +dotnet_style_null_propagation = true:suggestion +dotnet_style_object_initializer = true:suggestion +dotnet_style_operator_placement_when_wrapping = beginning_of_line +dotnet_style_prefer_auto_properties = true:suggestion +dotnet_style_prefer_compound_assignment = true:suggestion +dotnet_style_prefer_conditional_expression_over_assignment = true:silent +dotnet_style_prefer_conditional_expression_over_return = true:silent +dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion +dotnet_style_prefer_inferred_tuple_names = true:suggestion +dotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion +dotnet_style_prefer_simplified_boolean_expressions = true:suggestion +dotnet_style_prefer_simplified_interpolation = true:suggestion + +# Field preferences +dotnet_style_readonly_field = true:warning + +# Parameter preferences +dotnet_code_quality_unused_parameters = all:warning + +# Suppression preferences +dotnet_remove_unnecessary_suppression_exclusions = none + +#### C# Coding Conventions #### + +# var preferences +csharp_style_var_elsewhere = false:suggestion +csharp_style_var_for_built_in_types = false:suggestion +csharp_style_var_when_type_is_apparent = true:suggestion + +# Expression-bodied members +csharp_style_expression_bodied_accessors = true:suggestion +csharp_style_expression_bodied_constructors = false:suggestion +csharp_style_expression_bodied_indexers = true:suggestion +csharp_style_expression_bodied_lambdas = true:suggestion +csharp_style_expression_bodied_local_functions = false:suggestion +csharp_style_expression_bodied_methods = false:suggestion +csharp_style_expression_bodied_operators = false:suggestion +csharp_style_expression_bodied_properties = true:suggestion + +# Pattern matching preferences +csharp_style_pattern_matching_over_as_with_null_check = true:suggestion +csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion +csharp_style_prefer_not_pattern = true:suggestion +csharp_style_prefer_pattern_matching = true:silent +csharp_style_prefer_switch_expression = true:suggestion + +# Null-checking preferences +csharp_style_conditional_delegate_call = true:suggestion + +# Modifier preferences +csharp_prefer_static_local_function = true:suggestion +csharp_preferred_modifier_order = public,private,protected,internal,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,volatile,async:warning + +# Code-block preferences +csharp_prefer_braces = true:warning +csharp_prefer_simple_using_statement = true:suggestion + +# Expression-level preferences +csharp_prefer_simple_default_expression = true:suggestion +csharp_style_deconstructed_variable_declaration = true:suggestion +csharp_style_implicit_object_creation_when_type_is_apparent = true:suggestion +csharp_style_inlined_variable_declaration = true:suggestion +csharp_style_pattern_local_over_anonymous_function = true:suggestion +csharp_style_prefer_index_operator = true:suggestion +csharp_style_prefer_range_operator = true:suggestion +csharp_style_throw_expression = true:suggestion +csharp_style_unused_value_assignment_preference = discard_variable:suggestion +csharp_style_unused_value_expression_statement_preference = discard_variable:silent + +# 'using' directive preferences +csharp_using_directive_placement = outside_namespace:warning + +#### C# Formatting Rules #### + +# New line preferences +csharp_new_line_before_catch = true +csharp_new_line_before_else = true +csharp_new_line_before_finally = true +csharp_new_line_before_members_in_anonymous_types = true +csharp_new_line_before_members_in_object_initializers = true +csharp_new_line_before_open_brace = all +csharp_new_line_between_query_expression_clauses = true + +# Indentation preferences +csharp_indent_block_contents = true +csharp_indent_braces = false +csharp_indent_case_contents = true +csharp_indent_case_contents_when_block = true +csharp_indent_labels = one_less_than_current +csharp_indent_switch_labels = true + +# Space preferences +csharp_space_after_cast = false +csharp_space_after_colon_in_inheritance_clause = true +csharp_space_after_comma = true +csharp_space_after_dot = false +csharp_space_after_keywords_in_control_flow_statements = true +csharp_space_after_semicolon_in_for_statement = true +csharp_space_around_binary_operators = before_and_after +csharp_space_around_declaration_statements = false +csharp_space_before_colon_in_inheritance_clause = true +csharp_space_before_comma = false +csharp_space_before_dot = false +csharp_space_before_open_square_brackets = false +csharp_space_before_semicolon_in_for_statement = false +csharp_space_between_empty_square_brackets = false +csharp_space_between_method_call_empty_parameter_list_parentheses = false +csharp_space_between_method_call_name_and_opening_parenthesis = false +csharp_space_between_method_call_parameter_list_parentheses = false +csharp_space_between_method_declaration_empty_parameter_list_parentheses = false +csharp_space_between_method_declaration_name_and_open_parenthesis = false +csharp_space_between_method_declaration_parameter_list_parentheses = false +csharp_space_between_parentheses = false +csharp_space_between_square_brackets = false + +# Wrapping preferences +csharp_preserve_single_line_blocks = true +csharp_preserve_single_line_statements = true + +#### Naming styles #### + +# Naming rules + +dotnet_naming_rule.interface_should_be_begins_with_i.severity = warning +dotnet_naming_rule.interface_should_be_begins_with_i.symbols = interface +dotnet_naming_rule.interface_should_be_begins_with_i.style = begins_with_i + +dotnet_naming_rule.types_should_be_pascal_case.severity = warning +dotnet_naming_rule.types_should_be_pascal_case.symbols = types +dotnet_naming_rule.types_should_be_pascal_case.style = pascal_case + +dotnet_naming_rule.non_field_members_should_be_pascal_case.severity = warning +dotnet_naming_rule.non_field_members_should_be_pascal_case.symbols = non_field_members +dotnet_naming_rule.non_field_members_should_be_pascal_case.style = pascal_case + +dotnet_naming_rule.private_or_internal_field_should_be_begins_with__.severity = suggestion +dotnet_naming_rule.private_or_internal_field_should_be_begins_with__.symbols = private_or_internal_field +dotnet_naming_rule.private_or_internal_field_should_be_begins_with__.style = begins_with__ + +dotnet_naming_rule.constant_should_be_pascal_case.severity = warning +dotnet_naming_rule.constant_should_be_pascal_case.symbols = constant +dotnet_naming_rule.constant_should_be_pascal_case.style = pascal_case + +# Symbol specifications + +dotnet_naming_symbols.interface.applicable_kinds = interface +dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected +dotnet_naming_symbols.interface.required_modifiers = + +dotnet_naming_symbols.private_or_internal_field.applicable_kinds = field +dotnet_naming_symbols.private_or_internal_field.applicable_accessibilities = internal, private, private_protected +dotnet_naming_symbols.private_or_internal_field.required_modifiers = + +dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum +dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected +dotnet_naming_symbols.types.required_modifiers = + +dotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method +dotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected +dotnet_naming_symbols.non_field_members.required_modifiers = + +dotnet_naming_symbols.constant.applicable_kinds = field, local +dotnet_naming_symbols.constant.applicable_accessibilities = * +dotnet_naming_symbols.constant.required_modifiers = const + +# Naming styles + +dotnet_naming_style.pascal_case.required_prefix = +dotnet_naming_style.pascal_case.required_suffix = +dotnet_naming_style.pascal_case.word_separator = +dotnet_naming_style.pascal_case.capitalization = pascal_case + +dotnet_naming_style.begins_with_i.required_prefix = I +dotnet_naming_style.begins_with_i.required_suffix = +dotnet_naming_style.begins_with_i.word_separator = +dotnet_naming_style.begins_with_i.capitalization = pascal_case + +dotnet_naming_style.begins_with__.required_prefix = _ +dotnet_naming_style.begins_with__.required_suffix = +dotnet_naming_style.begins_with__.word_separator = +dotnet_naming_style.begins_with__.capitalization = camel_case + +#### Code Analysis Rules #### + +# Security Rules +dotnet_diagnostic.CA5350.severity = error # Do Not Use Weak Cryptographic Algorithms +dotnet_diagnostic.CA5351.severity = error # Do Not Use Broken Cryptographic Algorithms +dotnet_diagnostic.CA5379.severity = error # Do Not Use Weak Key Derivation Function Algorithm +dotnet_diagnostic.CA5385.severity = error # Use Rivest-Shamir-Adleman (RSA) Algorithm With Sufficient Key Size + +# Design Rules +dotnet_diagnostic.CA1031.severity = warning # Do not catch general exception types +dotnet_diagnostic.CA1062.severity = suggestion # Validate arguments of public methods +dotnet_diagnostic.CA1303.severity = silent # Do not pass literals as localized parameters + +# Performance Rules +dotnet_diagnostic.CA1806.severity = warning # Do not ignore method results +dotnet_diagnostic.CA1810.severity = warning # Initialize reference type static fields inline +dotnet_diagnostic.CA1819.severity = suggestion # Properties should not return arrays +dotnet_diagnostic.CA1822.severity = suggestion # Mark members as static + +# Usage Rules +dotnet_diagnostic.CA2200.severity = warning # Rethrow to preserve stack details +dotnet_diagnostic.CA2211.severity = warning # Non-constant fields should not be visible +dotnet_diagnostic.CA2234.severity = warning # Pass system uri objects instead of strings diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..9634b41 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,166 @@ +name: Bug Report +description: Report a bug or unexpected behavior in HeroCrypt +title: "[Bug]: " +labels: ["bug", "needs-triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the form below with as much detail as possible. + + **Note**: For security vulnerabilities, please DO NOT create a public issue. Instead, email security@herocrypt.dev (or repository maintainer). + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: When I try to..., I expect... but instead... + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Step-by-step instructions to reproduce the issue + placeholder: | + 1. Create an instance of... + 2. Call method... with parameters... + 3. Observe the error... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: I expected the method to return... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? + placeholder: Instead, it threw an exception / returned incorrect value... + validations: + required: true + + - type: textarea + id: code + attributes: + label: Code Sample + description: Please provide a minimal code sample that reproduces the issue + placeholder: | + ```csharp + var options = new Argon2Options { /* ... */ }; + var result = Argon2.Hash("password", salt, options); + // Bug occurs here... + ``` + render: csharp + validations: + required: false + + - type: textarea + id: stacktrace + attributes: + label: Stack Trace / Error Message + description: If applicable, include the full stack trace or error message + placeholder: | + System.ArgumentException: Invalid parameter + at HeroCrypt.Cryptography... + render: text + validations: + required: false + + - type: dropdown + id: dotnet-version + attributes: + label: .NET Version + description: Which .NET version are you using? + options: + - .NET 9.0 + - .NET 8.0 + - .NET 7.0 + - .NET 6.0 + - .NET Standard 2.0 + - Other (please specify in Additional Context) + validations: + required: true + + - type: input + id: herocrypt-version + attributes: + label: HeroCrypt Version + description: Which version of HeroCrypt are you using? + placeholder: e.g., 1.0.0 + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating System + description: Which operating system are you using? + options: + - Windows + - Linux + - macOS + - Other (please specify in Additional Context) + validations: + required: true + + - type: input + id: os-version + attributes: + label: OS Version + description: What version of the OS? + placeholder: e.g., Windows 11, Ubuntu 22.04, macOS 14 + validations: + required: false + + - type: dropdown + id: severity + attributes: + label: Severity + description: How severe is this bug? + options: + - Critical (security issue, data loss, crash) + - High (major functionality broken) + - Medium (functionality impaired) + - Low (cosmetic, minor inconvenience) + validations: + required: true + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context about the problem here + placeholder: | + - Hardware details (CPU, available memory) + - Specific configurations + - Related issues + - Workarounds you've tried + validations: + required: false + + - type: checkboxes + id: checklist + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have provided a minimal code sample that reproduces the issue + required: false + - label: I have included relevant error messages or stack traces + required: false + - label: This is not a security vulnerability (if it is, I will email security@herocrypt.dev instead) + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..9a6e868 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Security Vulnerability + url: mailto:security@herocrypt.dev + about: Please report security vulnerabilities via email, not as public issues + - name: GitHub Discussions + url: https://github.com/YourOrg/HeroCrypt/discussions + about: Ask questions and discuss ideas with the community + - name: Documentation + url: https://github.com/YourOrg/HeroCrypt/tree/main/docs + about: Browse our documentation and guides diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..d457142 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,171 @@ +name: Feature Request +description: Suggest a new feature or enhancement for HeroCrypt +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! Please fill out the form below to help us understand your request. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: Is your feature request related to a problem? Please describe. + placeholder: I'm frustrated when... / I need to... / It would be helpful if... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see + placeholder: I would like HeroCrypt to support... / Add a new method that... + validations: + required: true + + - type: dropdown + id: category + attributes: + label: Feature Category + description: What category does this feature fall into? + options: + - New cryptographic algorithm + - Performance improvement + - New API / helper method + - Documentation improvement + - Developer experience + - Security enhancement + - Compliance / standards support + - Hardware acceleration + - Platform support + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Critical (blocking my project) + - High (important for my use case) + - Medium (would be nice to have) + - Low (minor improvement) + validations: + required: true + + - type: textarea + id: use-case + attributes: + label: Use Case + description: Describe your specific use case for this feature + placeholder: | + I'm building an application that... and I need... + This would help with... + validations: + required: true + + - type: textarea + id: api-design + attributes: + label: Proposed API Design + description: If applicable, suggest an API design for this feature + placeholder: | + ```csharp + // Example usage + var result = NewFeature.DoSomething(parameters); + ``` + render: csharp + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Describe any alternative solutions or features you've considered + placeholder: | + I considered using... but... + Alternatively, we could... + validations: + required: false + + - type: textarea + id: implementation + attributes: + label: Implementation Ideas + description: If you have ideas on how to implement this, please share + placeholder: | + This could be implemented by... + We would need to... + Potential challenges: ... + validations: + required: false + + - type: dropdown + id: breaking-change + attributes: + label: Breaking Change + description: Would this feature require breaking changes to existing APIs? + options: + - "No - This is backward compatible" + - "Yes - This requires breaking changes" + - "Unsure" + validations: + required: true + + - type: textarea + id: standards + attributes: + label: Standards / References + description: Are there any RFCs, NIST standards, or academic papers related to this feature? + placeholder: | + RFC XXXX - ... + NIST SP 800-XXX - ... + Academic paper: ... + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Add any other context, screenshots, or examples about the feature request + placeholder: | + - Similar features in other libraries + - Performance considerations + - Security implications + validations: + required: false + + - type: checkboxes + id: contribution + attributes: + label: Contribution + description: Are you willing to help implement this feature? + options: + - label: I am willing to submit a pull request for this feature + required: false + - label: I can help with testing this feature + required: false + - label: I can help with documentation for this feature + required: false + + - type: checkboxes + id: checklist + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched existing issues and feature requests + required: true + - label: This feature aligns with HeroCrypt's goals (cryptographic library for .NET) + required: true + - label: I have described a clear use case for this feature + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7c5a400 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,167 @@ +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Performance improvement +- [ ] Code refactoring +- [ ] Security fix +- [ ] Test improvements + +## Related Issues + + + +Fixes # +Closes # +Related to # + +## Changes Made + + + +### Summary of Changes +- +- +- + +### Technical Details + + + +## Testing + + + +### Test Coverage +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Test vectors from official specifications included (if applicable) +- [ ] All existing tests pass +- [ ] New tests pass + +### Test Scenarios Covered +- +- + +### Manual Testing + + + +## Cryptographic Implementation Checklist + + + +- [ ] Implementation follows published standard (RFC, NIST, ISO) +- [ ] Reference to specification included in code comments +- [ ] Official test vectors included and passing +- [ ] Constant-time operations used where necessary +- [ ] Memory securely cleared after use +- [ ] Input validation is comprehensive +- [ ] Security warnings documented where appropriate +- [ ] No unsafe code (or well-justified if necessary) + +**Standard/Specification**: + +## Documentation + + + +- [ ] XML documentation added for new public APIs +- [ ] README.md updated (if needed) +- [ ] CHANGELOG.md updated +- [ ] Code comments added for complex logic +- [ ] Usage examples provided + +## Code Quality + +- [ ] Code follows project style guidelines +- [ ] EditorConfig settings applied +- [ ] No compiler warnings introduced +- [ ] Code has been self-reviewed +- [ ] Code is DRY (Don't Repeat Yourself) +- [ ] Naming conventions followed + +## Breaking Changes + + + +### Breaking Changes Description + + + +### Migration Guide + + + +## Performance Impact + + + +- [ ] No performance impact +- [ ] Performance improved (include benchmark results) +- [ ] Performance decreased (justified by security/correctness) +- [ ] Not applicable + +### Benchmark Results (if applicable) +``` + +``` + +## Security Considerations + + + +- [ ] No security impact +- [ ] Security improved +- [ ] New security considerations (documented) +- [ ] Not applicable + +### Security Impact Description + + + +## Deployment Notes + + + +- [ ] No special deployment needed +- [ ] Requires configuration changes +- [ ] Requires database migrations +- [ ] Other (describe below) + +## Screenshots / Logs + + + + +## Checklist + + + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] My code follows the project's code style +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published +- [ ] I have updated the CHANGELOG.md file + +## Additional Context + + + + +--- + +**By submitting this pull request, I confirm that my contribution is made under the terms of the MIT License.** diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 0000000..0d2add7 --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,84 @@ +name: "CodeQL Security Analysis" + +on: + push: + branches: [ "main", "develop" ] + pull_request: + branches: [ "main", "develop" ] + schedule: + # Run at 2 AM UTC every Monday + - cron: '0 2 * * 1' + workflow_dispatch: + +jobs: + analyze: + name: Analyze Code + runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} + timeout-minutes: ${{ (matrix.language == 'swift' && 120) || 360 }} + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'csharp' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' ] + # Use only 'java' to analyze code written in Java, Kotlin or both + # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both + # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: | + 6.0.x + 7.0.x + 8.0.x + 9.0.x + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + queries: +security-extended,security-and-quality + + # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift). + # If this step fails, then you should remove it and run the build manually + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + # ℹ️ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + + # If the Autobuild fails above, remove it and uncomment the following three lines. + # modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance. + + # - name: Build Project + # run: | + # dotnet restore + # dotnet build --configuration Release --no-restore + # dotnet test --no-build --verbosity normal + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" + + - name: Upload SARIF results + if: always() + uses: github/codeql-action/upload-sarif@v3 + with: + sarif_file: ${{ runner.temp }}/results + category: "/language:${{matrix.language}}" diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c1badf0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,182 @@ +# Changelog + +All notable changes to HeroCrypt will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Zero-Knowledge & Advanced Protocols (Phase 3F) - Reference implementations + - zk-SNARKs (Groth16-style) with trusted setup, proof generation, and verification + - Ring Signatures with basic, linkable, and traceable variants + - Threshold Signatures supporting Schnorr, ECDSA, EdDSA, and BLS schemes + - Multi-Party Computation with secure sum, multiplication, and private set intersection + - Comprehensive test suite with 35+ test cases for advanced protocols +- Post-Quantum Cryptography (Phase 3E) - Reference implementations + - CRYSTALS-Kyber (ML-KEM, FIPS 203) key encapsulation mechanism + - CRYSTALS-Dilithium (ML-DSA, FIPS 204) digital signatures + - SPHINCS+ (SLH-DSA, FIPS 205) stateless hash-based signatures + - Multiple security levels (128-bit, 192-bit, 256-bit post-quantum) +- Key Derivation & Management (Phase 3D) + - Shamir's Secret Sharing with GF(256) finite field arithmetic + - BIP32 Hierarchical Deterministic Wallets + - BIP39 Mnemonic Codes for seed generation (12/15/18/21/24 words) + - Balloon Hashing for memory-hard password hashing +- Advanced Symmetric Algorithms (Phase 3C) + - AES-OCB (Offset Codebook Mode) - RFC 7253 AEAD + - HC-256 stream cipher (eSTREAM portfolio, 256-bit security) + - RC4 stream cipher (legacy compatibility with security warnings) +- Project infrastructure and community guidelines + - SECURITY.md with vulnerability reporting policy + - CONTRIBUTING.md with comprehensive contribution guidelines + - CHANGELOG.md for version tracking + - EditorConfig for consistent code style + - GitHub issue and pull request templates + - Dependabot configuration for automated dependency updates + - CodeQL security scanning workflow + +### Changed +- Updated DEVELOPMENT_ROADMAP.md marking Phases 3C, 3D, 3E, and 3F as completed +- Enhanced README.md with all new cryptographic features +- Improved documentation with production requirement warnings for reference implementations + +### Security +- Added comprehensive security policy and vulnerability reporting process +- Documented security best practices for HeroCrypt usage +- Identified and clearly marked reference implementations requiring full production implementations + +## [0.9.0] - 2024-12-XX (Phase 3B Complete) + +### Added +- Modern Symmetric Cryptography (Phase 3B) + - ChaCha20-Poly1305 (RFC 8439) with SIMD optimizations + - XChaCha20-Poly1305 (extended 24-byte nonce) + - AES-GCM with hardware acceleration + - AES-CCM (RFC 3610) + - AES-SIV (RFC 5297) - nonce-misuse resistant + - Streaming encryption support +- Performance benchmarking framework structure + +### Changed +- Optimized ChaCha20 with AVX2 SIMD instructions +- Enhanced AEAD framework for authenticated encryption + +## [0.8.0] - 2024-11-XX (Phase 3A Complete) + +### Added +- Elliptic Curve Cryptography (Phase 3A) + - Curve25519 (X25519 key exchange) + - Ed25519 (digital signatures) + - Secp256k1 (Bitcoin-compatible) + - Hardware-accelerated field arithmetic + - Comprehensive ECC service interface + +### Changed +- Improved ECC performance with optimized field operations + +## [0.7.0] - 2024-10-XX (Phase 2 Complete) + +### Added +- Infrastructure & Security Hardening (Phase 2) + - Hardware acceleration detection (AVX2, AES-NI) + - Secure memory management with automatic zeroing + - Constant-time comparison operations + - Fluent API builders for common scenarios + - Comprehensive testing framework + - Security policies and configuration system + - Observability and telemetry infrastructure + +### Changed +- Refactored core algorithms for better performance +- Enhanced error handling and validation + +### Security +- Implemented constant-time operations for sensitive comparisons +- Added secure memory management for key material +- Improved side-channel attack resistance + +## [0.6.0] - 2024-09-XX (Phase 1 Complete) + +### Added +- Foundation & Core Algorithms (Phase 1) + - Argon2 Password Hashing (Argon2d, Argon2i, Argon2id) + - Full RFC 9106 compliance + - Configurable memory, iterations, and parallelism + - Secure salt generation + - Blake2b Hashing + - Full RFC 7693 compliance + - Variable output sizes (1-64 bytes) + - Keyed hashing (MAC) support + - Blake2b-Long for outputs > 64 bytes + - RSA Encryption & Digital Signatures + - PKCS#1 v2.2 support + - Key generation (512-4096 bits) + - PKCS#1 v1.5 and OAEP padding + - PGP-compatible Encryption + - Hybrid encryption with AES session keys + - RSA key pair support + - Passphrase protection for private keys + - Multi-framework targeting (.NET Standard 2.0, .NET 6-9) + - Dependency injection support + +### Changed +- Initial release architecture and project structure + +## [0.1.0] - 2024-08-XX (Initial Release) + +### Added +- Project initialization +- Basic project structure +- NuGet package configuration +- CI/CD pipeline setup +- Initial documentation + +--- + +## Release Types + +### Major Releases (x.0.0) +- Breaking API changes +- Major architectural changes +- Removal of deprecated features + +### Minor Releases (0.x.0) +- New features (backward compatible) +- New algorithm implementations +- Performance improvements +- Deprecated features (with migration path) + +### Patch Releases (0.0.x) +- Bug fixes +- Security patches +- Documentation improvements +- Minor performance optimizations + +## Deprecation Policy + +- Features marked as deprecated will be supported for at least 2 minor versions +- Deprecation warnings will be added via `[Obsolete]` attributes +- Migration guides will be provided in release notes +- Security-critical deprecations may be expedited + +## Security Updates + +Security vulnerabilities will be addressed with highest priority: +- **Critical**: Immediate patch release within 24-48 hours +- **High**: Patch release within 7 days +- **Medium**: Included in next scheduled release +- **Low**: Included in next minor release + +## Links + +- [Homepage](https://github.com/YourOrg/HeroCrypt) +- [Documentation](https://github.com/YourOrg/HeroCrypt/tree/main/docs) +- [Issue Tracker](https://github.com/YourOrg/HeroCrypt/issues) +- [NuGet Package](https://www.nuget.org/packages/HeroCrypt) + +--- + +*This changelog is maintained by the HeroCrypt development team.* +*For security advisories, see [SECURITY.md](SECURITY.md).* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5b78178 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,494 @@ +# Contributing to HeroCrypt + +First off, thank you for considering contributing to HeroCrypt! 🎉 + +HeroCrypt is a community-driven cryptographic library, and we welcome contributions from developers of all skill levels. This document provides guidelines for contributing to the project. + +## 📋 Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Coding Standards](#coding-standards) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Cryptographic Implementation Guidelines](#cryptographic-implementation-guidelines) +- [Testing Requirements](#testing-requirements) +- [Documentation](#documentation) + +## 📜 Code of Conduct + +This project adheres to a Code of Conduct that all contributors are expected to follow. Please be respectful, inclusive, and professional in all interactions. + +**Expected Behavior:** +- Be respectful and considerate +- Welcome newcomers and help them learn +- Focus on what is best for the community +- Show empathy towards other community members + +**Unacceptable Behavior:** +- Harassment, discrimination, or offensive comments +- Trolling, insulting, or derogatory comments +- Publishing others' private information +- Any conduct that could be considered inappropriate in a professional setting + +## 🚀 Getting Started + +### Prerequisites + +- **.NET SDK**: Version 6.0 or later +- **Git**: For version control +- **IDE**: Visual Studio 2022, VS Code, or JetBrains Rider +- **Understanding of C#**: Intermediate to advanced level +- **Cryptography knowledge**: Basic understanding helpful but not required for all contributions + +### First-Time Contributors + +If this is your first time contributing: + +1. Look for issues tagged with `good first issue` or `help wanted` +2. Read through the documentation to understand the project structure +3. Ask questions in GitHub Discussions if you need help +4. Start with small changes to familiarize yourself with the codebase + +## 🤝 How Can I Contribute? + +### 1. Reporting Bugs + +**Before submitting a bug report:** +- Check the existing issues to avoid duplicates +- Verify the bug exists in the latest version +- Collect relevant information (OS, .NET version, error messages) + +**When submitting a bug report, include:** +- Clear, descriptive title +- Step-by-step reproduction instructions +- Expected vs. actual behavior +- Code samples demonstrating the issue +- Environment details (.NET version, OS, hardware) +- Stack traces or error messages + +### 2. Suggesting Enhancements + +**Before suggesting an enhancement:** +- Check if it's already been suggested +- Ensure it aligns with the project's goals +- Consider if it's broadly useful to users + +**When suggesting an enhancement:** +- Use a clear, descriptive title +- Provide detailed explanation of the proposed feature +- Explain the use case and benefits +- Include code examples if applicable +- Suggest implementation approach if you have ideas + +### 3. Contributing Code + +**Types of contributions we welcome:** +- **Bug fixes**: Fix reported issues +- **New algorithms**: Implement cryptographic algorithms following standards +- **Performance improvements**: Optimize existing implementations +- **Tests**: Add or improve test coverage +- **Documentation**: Improve docs, examples, or comments +- **Tooling**: Enhance build scripts, CI/CD, or development tools + +## 💻 Development Setup + +### Clone the Repository + +```bash +git clone https://github.com/YourOrg/HeroCrypt.git +cd HeroCrypt +``` + +### Build the Project + +```bash +dotnet restore +dotnet build +``` + +### Run Tests + +```bash +dotnet test +``` + +### Project Structure + +``` +HeroCrypt/ +├── src/ +│ └── HeroCrypt/ # Main library +│ ├── Cryptography/ # Cryptographic implementations +│ ├── Services/ # High-level service APIs +│ └── Utilities/ # Helper classes +├── tests/ +│ └── HeroCrypt.Tests/ # Unit and integration tests +├── benchmarks/ +│ └── HeroCrypt.Benchmarks/ # Performance benchmarks (planned) +└── docs/ # Documentation +``` + +## 📝 Coding Standards + +### C# Style Guidelines + +We follow standard .NET coding conventions with some specific guidelines: + +#### Naming Conventions +- **Classes**: PascalCase (`Argon2HashingService`) +- **Methods**: PascalCase (`ComputeHash`) +- **Parameters**: camelCase (`hashLength`) +- **Private fields**: camelCase with underscore (`_context`) +- **Constants**: PascalCase (`DefaultIterations`) +- **Interfaces**: I prefix (`IHashingService`) + +#### Code Style +```csharp +// ✅ Good +public byte[] ComputeHash(ReadOnlySpan data, int outputLength) +{ + if (data.Length == 0) + throw new ArgumentException("Data cannot be empty", nameof(data)); + + var result = new byte[outputLength]; + // Implementation... + return result; +} + +// ❌ Bad +public byte[] compute_hash(byte[] data,int len) { + if(data.Length==0) throw new Exception("empty"); + byte[] result=new byte[len]; + return result; +} +``` + +#### Code Organization +- One class per file +- Related classes in same namespace +- Keep methods focused and concise (< 50 lines ideally) +- Use regions sparingly, prefer clear class structure + +#### XML Documentation +All public APIs must have XML documentation: + +```csharp +/// +/// Computes a Blake2b hash of the input data. +/// +/// The data to hash +/// Desired hash length in bytes (1-64) +/// The computed hash +/// Thrown when outputLength is invalid +public static byte[] ComputeHash(ReadOnlySpan data, int outputLength) +{ + // Implementation... +} +``` + +### EditorConfig + +The project includes an `.editorconfig` file. Configure your IDE to use it for automatic formatting. + +## 📌 Commit Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/) specification. + +### Commit Message Format + +``` +(): + + + +