Skip to content

Latest commit

 

History

History
479 lines (363 loc) · 12.8 KB

CONTRIBUTING.md

File metadata and controls

479 lines (363 loc) · 12.8 KB

Contributing to SSCG

Thank you for your interest in contributing to SSCG (Simple Signed Certificate Generator)! This document provides guidelines for contributing to the project.

Table of Contents

Getting Started

Prerequisites

Before contributing, ensure you have the necessary tools installed:

Fedora/RHEL/CentOS:

sudo dnf install meson ninja-build gcc pkgconf-pkg-config \
                 openssl-devel libtalloc-devel popt-devel \
                 libpath_utils-devel gettext-devel help2man \
                 clang-format git

Ubuntu/Debian:

sudo apt-get install meson ninja-build gcc pkg-config libssl-dev \
                           libtalloc-dev libpopt-dev libpath-utils-dev \
                           gettext help2man clang-format git

Setting Up Your Development Environment

  1. Fork and clone the repository: Fork the Github repository and then run:

    git clone https://github.com/your-username/sscg.git
cd sscg
git remote add upstream https://github.com/sgallagher/sscg.git

  2. Build the project:

    meson setup build
meson compile -C build

  3. Run tests to ensure everything works:

    meson test -C build

Development Container (Optional)

For a consistent development environment, you can use the provided devcontainer:

  1. Install Podman (recommended) or Docker
  2. Install VS Code with Dev Containers extension
  3. Open project in VS Code and select "Reopen in Container"

See .devcontainer/README.md for detailed instructions.

Development Environment

Project Structure

  • src/ - Main source code
    • sscg.c - Main application entry point
    • arguments.c - Command-line argument parsing
    • authority.c - Certificate Authority management
    • cert.c - Certificate creation and signing
    • x509.c - X.509 certificate operations
    • key.c - Key generation and management
    • io_utils.c - File I/O operations
    • dhparams.c - Diffie-Hellman parameter generation
  • include/ - Header files
  • test/ - Unit tests and integration tests
  • po/ - Internationalization files

Memory Management

SSCG uses talloc for all dynamic memory allocation:

  • Always use talloc functions (talloc_*) instead of malloc()/free()
  • Use TALLOC_CTX for hierarchical memory management
  • Follow parent-child relationships for automatic cleanup
  • Enable leak detection in tests with talloc_enable_leak_report_full()

The most common pattern is to always create a tmp_ctx from NULL in each function that allocates memory and always call talloc_free(tmp_ctx) before returning. If the function needs to return some allocated objects, use talloc_steal() to reassign that memory to a mem_ctx passed into the function just before the function returns.

The purpose of using NULL for the tmp_ctx parent is so that leaks will be detectable if the function exits without calling talloc_free(tmp_ctx);. If it's allocated onto the mem_ctx from the beginning, the leak will be invisible.

Example:

int
my_func(TALLOC_CTX *mem_ctx, struct custom_data **data)
{
  TALLOC_CTX *tmp_ctx = talloc_new (NULL);
  struct custom_data *tmp_data = talloc_zero (tmp_ctx, struct custom_data);

  // do stuff here, if errors occur, set `ret` to non-zero and `goto done`
  // CHECK_OK() will call `goto done` on nonzero
  ret = func_that_might_fail()
  CHECK_OK (ret);

  *data = talloc_steal(mem_ctx, tmp_data);
  ret = EOK;

done:
  talloc_free (tmp_ctx);
  return ret;
}

When allocating memory, use an appropriate hierarchy. A talloc_free() will recursively descend and free the memory from the bottom-up, so you want to have struct members use the struct itself as the parent, array entries use the array as the parent, etc.

Error Handling

  • Use CHECK_OK() macro for error propagation
  • Return appropriate errno values (EOK for success)
  • Clean up resources on error paths
  • Provide meaningful error messages to users

Example:

ret = some_function(ctx, &result);
CHECK_OK(ret);  // Automatically handles error propagation

Code Standards

Code Formatting

SSCG uses clang-format with a WebKit-based style:

# Format all source files
clang-format -i src/*.c include/*.h test/*.c

# Or format specific files
clang-format -i path/to/file.c

Key formatting rules:

  • Function return types on separate lines
  • No short functions on single lines
  • Align function parameters when wrapping
  • Use spaces, not tabs
  • 80-character line limit where reasonable

Coding Conventions

  • Use descriptive variable names
  • Prefix functions with sscg_ for public APIs
  • Use static for internal functions
  • Include proper error checking for all operations
  • Document complex algorithms with comments
  • Follow existing patterns in the codebase

Header Files

  • Include guards using #ifndef/#define/#endif
  • Forward declarations to minimize dependencies
  • Proper copyright headers (see License section)

Testing

Test Structure

SSCG uses a custom testing framework with the following patterns:

  • Unit tests for individual functions (test/*_test.c)
  • Integration tests for end-to-end functionality (test/test_*.sh)
  • Memory leak detection using talloc reporting
  • Multiple test cases for different parameters

Writing Tests

Unit Test Example:

int main(int argc, char **argv)
{
    int ret;
    TALLOC_CTX *tmp_ctx = talloc_new(NULL);
    
    // Enable memory leak detection
    talloc_enable_leak_report_full();
    
    printf("=== Test Description ===\n");
    
    // Test case 1
    printf("Testing basic functionality. ");
    ret = your_function(tmp_ctx, &result);
    if (ret != EOK) {
        printf("FAILED.\n");
        goto done;
    }
    printf("SUCCESS.\n");
    
    // Verify results
    printf("Verifying results. ");
    if (result != expected) {
        printf("FAILED.\n");
        ret = EINVAL;
        goto done;
    }
    printf("SUCCESS.\n");
    
done:
    talloc_free(tmp_ctx);
    return ret;
}

Running Tests

# Run all tests
meson test -C build

# Run specific test
meson test -C build test_name

# Run with verbose output
meson test -C build --verbose

# Run slow tests (DH parameter generation)
meson setup build -Drun_slow_tests=true
meson test -C build

Test Categories

  1. Fast tests (< 30 seconds): Basic functionality, key generation, certificate creation
  2. Slow tests (> 30 seconds): DH parameter generation, large key sizes
  3. Integration tests: Full certificate chain creation, file I/O operations

Submitting Changes

Before Submitting

  1. Ensure all tests pass:

    meson test -C build

  2. Format your code:

    clang-format -i $(find . -name "*.[ch]")

  3. Check for memory leaks:

    SSCG_TALLOC_REPORT=true ./build/sscg

  4. Test on multiple platforms if possible (Fedora, Ubuntu, etc.)

  5. Update translations if you added user-facing strings:

    meson compile -C build sscg-pot
meson compile -C build sscg-update-po

Commit Guidelines

Commit Message Format:

Short summary (50 characters or less)

Detailed explanation of the changes, including:
- What was changed and why
- Any breaking changes
- References to issues or discussions

Signed-off-by: Your Name <your.email@example.com>

Example:

Add support for ECDSA P-384 curve

- Implement P-384 curve support in key generation
- Add curve validation in arguments parsing  
- Update tests to cover P-384 functionality
- Add documentation for new --ec-curve option

Fixes: #123
Signed-off-by: Jane Developer <jane@example.com>

Pull Request Process

  1. Create a feature branch:

    git checkout -b your-feature-name

  2. Make your changes following the guidelines above

  3. Push to your fork:

    git push origin your-feature-name

  4. Create a pull request with:

    • Clear description of changes
    • Rationale for the change
    • Test results
    • Any breaking changes noted
    • References to related issues

  5. Respond to review feedback promptly

  6. Ensure CI passes on all platforms

License and Copyright

License

SSCG is licensed under GPL-3.0-or-later WITH OpenSSL-exception. All contributions must be compatible with this license.

Copyright Headers

All source files must include the following copyright header:

/*
 * SPDX-License-Identifier: GPL-3.0-or-later WITH cryptsetup-OpenSSL-exception
 * This file is part of sscg.
 *
 * sscg is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * sscg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with sscg.  If not, see <http://www.gnu.org/licenses/>.
 *
 * In addition, as a special exception, the copyright holders give
 * permission to link the code of portions of this program with the
 * OpenSSL library under certain conditions as described in each
 * individual source file, and distribute linked combinations
 * including the two.
 * You must obey the GNU General Public License in all respects
 * for all of the code used other than OpenSSL.  If you modify
 * file(s) with this exception, you may extend this exception to your
 * version of the file(s), but you are not obligated to do so.  If you
 * do not wish to do so, delete this exception statement from your
 * version.  If you delete this exception statement from all source
 * files in the program, then also delete it here.
 *
 * Copyright XXXX by Your Name <yourname@yoursite.com>
 */

Developer Certificate of Origin

By contributing to this project, you certify that:

  1. The contribution was created in whole or in part by you and you have the right to submit it under the open source license indicated in the file
  2. The contribution is based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license
  3. You understand and agree that this project and the contribution are public

Add a Signed-off-by line to your commits:

git commit -s -m "Your commit message"

Security Issues

Do not file public issues for security vulnerabilities.

For security-related issues, please contact the maintainer directly:

Include:

  • Description of the vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (if any)

Community Guidelines

Bug Reports

When reporting bugs, include:

  • SSCG version: sscg --version
  • Operating system and version
  • OpenSSL version: openssl version
  • Complete command line used
  • Expected vs. actual behavior
  • Error messages (if any)
  • Steps to reproduce

Feature Requests

For feature requests:

  • Describe the use case clearly
  • Explain why the feature would be valuable
  • Provide examples of how it would be used
  • Consider backwards compatibility

Communication

  • Be respectful and professional
  • Stay on topic in discussions
  • Provide constructive feedback
  • Help others when possible
  • Follow the code of conduct

Development Tips

Debugging

GDB debugging:

gdb --args ./build/sscg --debug [options]

Valgrind for memory checking:

valgrind --leak-check=full --show-leak-kinds=all ./build/sscg [options]

Talloc memory reporting:

SSCG_TALLOC_REPORT=true ./build/sscg [options]

Build Variants

Debug build:

meson setup build --buildtype=debug

Release build:

meson setup build --buildtype=release

With additional warnings:

meson setup build -Dwarning_level=3

Useful Resources

Thank you for contributing to SSCG! Your contributions help make secure certificate generation accessible to everyone.