From 7d190d32cf9dc3426ce05ad93a493193a5f6c3c4 Mon Sep 17 00:00:00 2001 From: David Walter Date: Thu, 28 May 2026 09:07:09 +0200 Subject: [PATCH] =?UTF-8?q?docs(ospo):=20community=20health=20rollout=20v2?= =?UTF-8?q?=20=E2=80=94=20README,=20agents.md,=20health=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduced by the Kiteworks Open Source Program Office (OSPO) on May 5, 2026. Changes: - README.md: rewritten with OSPO v2 template — license-specific migration guidance, Community & Support section, Contributing workflow, Security section pointing to security.owncloud.com + YesWeHack bug bounty - agents.md: AI agent context file with architecture, build commands, and OSPO Policy Constraints (GitHub Actions, Dependabot, Git Workflow) - CODE_OF_CONDUCT.md: redirect to https://owncloud.com/contribute/code-of-conduct/ - CONTRIBUTING.md: redirect to https://owncloud.com/contribute/ - SECURITY.md: redirect to https://security.owncloud.com + YesWeHack - SUPPORT.md: redirect to https://owncloud.com/contact-us/ + channels OSPO: https://kiteworks.com/opensource Signed-off-by: David Walter --- CODE_OF_CONDUCT.md | 8 +++ CONTRIBUTING.md | 9 ++++ README.md | 119 +++++++++++++++++++++++++++++++++++---------- SECURITY.md | 11 +++++ SUPPORT.md | 10 ++++ agents.md | 69 ++++++++++++++++++++++++++ 6 files changed, 200 insertions(+), 26 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 agents.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ce144bf --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..65c9915 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +Please read the full contributing guidelines at: +**** + +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index 5758a10..7f95454 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,106 @@ -# encryption - :lock_with_ink_pen: server side encryption of files - - [![Build Status](https://drone.owncloud.com/api/badges/owncloud/encryption/status.svg)](https://drone.owncloud.com/owncloud/encryption) -[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=owncloud_encryption&metric=alert_status)](https://sonarcloud.io/dashboard?id=owncloud_encryption) -[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=owncloud_encryption&metric=security_rating)](https://sonarcloud.io/dashboard?id=owncloud_encryption) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=owncloud_encryption&metric=coverage)](https://sonarcloud.io/dashboard?id=owncloud_encryption) +# ownCloud Encryption -In order to use this encryption module you need to enable server-side -encryption in the admin settings. Once enabled this module will encrypt -all your files transparently. The encryption is based on AES 256 keys. -The module won't touch existing files, only new files will be encrypted -after server-side encryption was enabled. It is also not possible to -disable the encryption again and switch back to a unencrypted system. -Please read the documentation to know all implications before you decide -to enable server-side encryption. + -## The following occ commands are not documented in the official documentation but added here for completness +[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/server) -The values bellow mostly represent internal configuration state and should not be set by the user directly. They are controlled by respective encryption-commands. Change only if you know what you are doing or are debugging. +An ownCloud Classic (OC10) app that provides transparent server-side encryption of files using AES-256 keys. Once enabled in the admin settings, all newly uploaded files are encrypted at rest. The module supports master key encryption, per-user keys, recovery keys, and optional HSM (Hardware Security Module) integration for key storage. -`config:app:set encryption masterKeyId --value ??` +## Getting Started -`config:app:set encryption recoveryKeyId --value ??` +Enable server-side encryption via the ownCloud admin settings or the command line: -The ID of the respective key. Background: Instead of giving a path to a keyfile (which might be error-prone) an explicit key-id which is part of the key is given. This is also done to accomodate for Keystorages which might not be file-based. +```bash +sudo -u www-data php occ encryption:enable +sudo -u www-data php occ encryption:select-encryption-type masterkey +sudo -u www-data php occ encryption:encrypt-all +``` -`config:app:set encryption useMasterKey --value 1/0` +**Important:** Once enabled, encryption cannot be disabled. Read the documentation thoroughly before enabling. Requires OpenSSL 1.1.x (see repository notes regarding OpenSSL 3.x compatibility). -Is masterkey encryption enabled? +## Documentation -`config:app:set encryption crypto.engine --value 'internal | hsm'` +- [ownCloud Encryption Documentation](https://doc.owncloud.com/server/latest/admin_manual/configuration/files/encryption/) +- [ownCloud Server Admin Manual](https://doc.owncloud.com/server/latest/admin_manual/) -Normal ownCloud encryption vs storing decryption-keys in a HSM +## Part of ownCloud Classic (OC10) -`config:app:set encryption recoveryAdminEnabled --value 1/0` +This app extends [ownCloud Server](https://github.com/owncloud/core) with server-side file encryption. It is shipped as part of the [ownCloud Server Docker image](https://hub.docker.com/r/owncloud/server). +## Community & Support -> Note : You need openSSL version 1.1.x installed for encryption app to work. With the release change of openSSL v1.x to openSSL version 3.x in December 2021, some ciphers which were valid in version 1.x, have been retired with immediate effect. This impacts the ownCloud encryption app. Your encryption environment will break due to openSSL v3 retired (legacy) ciphers. As a result, encrypted files cant be accessed. As a temporary solution, you have to manually reenable in the openSSL v3 config the legacy ciphers. To do so, see the example in the OpenSSL 3.0 Wiki at section 6.2 Providers. \ No newline at end of file +**[Star](https://github.com/owncloud/encryption)** this repo and **Watch** for release notifications! + +- [ownCloud Website](https://owncloud.com) +- [Community Discussions](https://github.com/orgs/owncloud/discussions) +- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org) +- [Documentation](https://doc.owncloud.com) +- [Enterprise Support](https://owncloud.com/contact-us/) +- [OSPO Home](https://kiteworks.com/opensource) + +## Contributing + +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. + +### Workflow + +- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR. +- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly. +- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification). +- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line: + ``` + git commit -s -S -m "your commit message" + ``` +- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), or (c) verified in the GitHub Marketplace. + +## Translations + +Help translate this project on Transifex: +**** + +Please submit translations via Transifex -- do not open pull requests for translation changes. + +## Security + +**Do not open a public GitHub issue for security vulnerabilities.** + +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). + +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) + +## License + +This project is licensed under the [AGPL-3.0](LICENSE). + +## About the ownCloud OSPO + +The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under +the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source +ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance, +community health, and sustainable collaboration between the open source community and +[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023. + +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: + +For questions about the OSPO or licensing, contact ospo@kiteworks.com. + +### License Migration to Apache 2.0 + +The OSPO is driving a strategic relicensing of ownCloud repositories toward the +[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), following +the [Apache Software Foundation's third-party license policy](https://www.apache.org/legal/resolved.html). + +Individual repositories will migrate as their audit is completed. The LICENSE file +in each repo reflects its **current** license status (not the target). + +**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works). + +Migration prerequisites for this repository: + +- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing +- **Copyleft dependency audit**: All AGPL/GPL dependencies must be replaced or isolated +- **KDE heritage review**: Any code with KDE-era copyrights requires legal analysis +- **Complete relicensing**: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..78094ae --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Security Policy + +## Reporting a Vulnerability + +**Do NOT open a public GitHub issue for security vulnerabilities.** + +Please report security issues responsibly via: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..d87c0ca --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..a7c95bc --- /dev/null +++ b/agents.md @@ -0,0 +1,69 @@ +# AI Agent Guidelines for ownCloud Encryption + +This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository. + +## Repository Overview +- **Product family:** Classic (OC10) +- **Primary language(s):** PHP +- **Build system:** Make + Composer +- **Test framework:** PHPUnit +- **CI system:** GitHub Actions + +## Architecture & Key Paths + +- `appinfo/` -- App metadata and registration +- `lib/` -- PHP application logic (encryption providers, key managers) +- `js/` -- Frontend JavaScript +- `css/` -- Stylesheets +- `templates/` -- PHP templates +- `tests/` -- PHPUnit tests +- `l10n/` -- Translations +- `Makefile` -- Build and test targets + +## Development Conventions +- **Branching:** master +- **Commit messages:** DCO sign-off required (`git commit -s`) +- **Code style:** PHP-CS-Fixer (ownCloud codestyle) and PHP_CodeSniffer (`phpcs.xml`) +- **PR process:** Open a PR against `master`. All CI checks must pass. + +## Build & Test Commands +```bash +# Build +make dist + +# Test +make test-php-unit + +# Lint +make test-php-style +``` + +## Important Constraints +- All code contributions must be compatible with the **AGPL-3.0** license +- Do not introduce new **copyleft-licensed dependencies** (GPL, AGPL, LGPL, MPL) without explicit discussion in an issue first. This is especially important for repos migrating to Apache 2.0. +- Do not introduce new dependencies without discussion in an issue first + + +## OSPO Policy Constraints + +### GitHub Actions +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@ # vX.Y.Z` +- Never introduce actions from unverified third parties. + +### Dependency Management +- Dependabot is configured for automated dependency updates. +- Review and merge Dependabot PRs as part of regular maintenance. +- Do not introduce new dependencies without discussion in an issue first. + +### Git Workflow +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. + +## Context for AI Agents +- Match existing code style +- Do not refactor unrelated code in the same PR +- Write tests for new functionality +- Keep PRs focused and atomic