{"id":20347794,"url":"https://github.com/itext/certomancer-as-a-service","last_synced_at":"2025-04-12T01:03:21.707Z","repository":{"id":84629905,"uuid":"481203979","full_name":"itext/certomancer-as-a-service","owner":"itext","description":"PKI testing container with Java integration.","archived":false,"fork":false,"pushed_at":"2022-04-13T12:24:57.000Z","size":126,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-12T01:03:13.976Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-13T12:18:27.000Z","updated_at":"2024-04-05T06:44:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"98b3042c-4bda-491c-bed6-47edc9aec284","html_url":"https://github.com/itext/certomancer-as-a-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itext%2Fcertomancer-as-a-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itext%2Fcertomancer-as-a-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itext%2Fcertomancer-as-a-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itext%2Fcertomancer-as-a-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itext","download_url":"https://codeload.github.com/itext/certomancer-as-a-service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501865,"owners_count":21114683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T22:18:08.210Z","updated_at":"2025-04-12T01:03:21.691Z","avatar_url":"https://github.com/itext.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Certomancer-as-a-Service\n\n\nThis repository contains two components:\n\n - A containerised version of [Certomancer](https://github.com/MatthiasValvekens/certomancer) with live configuration management support.\n - A Java client with some additional integrations that make it easier to use the container in automated tests (in a Java project).\n\n\n## The Certomancer-as-a-Service container\n\nThe sample `docker-compose.yml` file in `certomancer-service-docker` declares three containers:\n\n - A `certomancer-as-a-service` container that exposes the Certomancer instance as a WSGI application using uWSGI.\n - A `redis` container to serve as the backend for the configuration management logic in the `certomancer-as-a-service` application.\n - A `nginx` container to expose a minimal HTTP frontend for the `certomancer-as-a-service` container.\n\nThe setup also includes a `sample-cfg` directory with some sample key pairs and configuration.\n\n\n### Basic setup\n\n\nTo spin up the sample config, change to the `certomancer-service-docker` folder and run\n\n```\n$ docker-compose build\n$ docker-compose up\n```\n\nas an account with access to the docker daemon.\n\n\nOnce the service is running, try POSTing some ad hoc config to it using `curl`:\n\n```\ncurl --data-binary @ad-hoc-samples/typical-ocsp-scenario.yml 'http://localhost:9000/config' \n```\n\nIf all is well, you should receive a large amount of JSON data as a response.\n\n\n### Advanced setup\n\nIf you already have a `nginx` server running on the machine on which you intend to deploy the container, you may wish to have that server handle traffic to the Certomancer-as-a-Service application, instead of routing it to a dedicated `nginx` container (as is the case in the sample config). Note that this requires the `ngx_http_uwsgi_module` to be enabled.\n\n\nIn its most simple form, this is what the configuration of such a frontend looks like.\n\n```\nserver {\n    listen 80;\n    location / {\n        include uwsgi_params;\n        uwsgi_pass INTERNAL_IP_OF_CERTOMANCER_CONTAINER:PORT;\n    }\n}\n```\n\nNote: if you decide to rewrite any URLs before passing them to the Certomancer container, please make sure to set up the [prefix for generated URLs in PKIX data](https://github.com/MatthiasValvekens/certomancer/blob/master/docs/config.md#general-structure) to account for that.\nThe `external-url-prefix` parameter should reflect the base URL to the Certomancer application, as seen from the point of view of the client.\n\n\nIn addition to replacing the `nginx` container with your own `nginx` server, you can of course also supply your own configuration to the `certomancer-as-a-service` container. The application reads its configuration from `/certomancer` (in the sample `docker-compose` setup, the `certomancer-service-docker/sample-cfg` directory is mounted at that location).\nThe `/certomancer` directory should contain at least a `certomancer.yml` file with some global config (e.g. declaring key sets), and a `keys` directory with available key files.\nIf you need inspiration, take a look at the files in the sample config directory.\n\n\n## Test client integrations for Java\n\nThis Maven project supplies some Java client-side tooling for use with a Certomancer-as-a-Service container.\n\nIt has two subprojects:\n\n - `certomancer-config`: basic, framework-neutral abstractions to handle the process of submitting configuration to the Certomancer container, and decoding responses from the configuration API.\n - `certomancer-junit`: further integration to avoid boilerplate in JUnit tests that rely on Certomancer.\n\n\n### Setting up shop\n\n\nMaven dependency:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.itextpdf\u003c/groupId\u003e\n    \u003cartifactId\u003ecertomancer-config\u003c/artifactId\u003e\n    \u003cversion\u003e1.0-SNAPSHOT\u003c/version\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nUsing dynamic certificates \u0026 trust services supplied by Certomancer requires a `CertomancerConfig`.\nIf the instance you want to talk to listens at `http://localhost:9000`, this is all you have to do:\n\n```java\nCertomancerConfigManager manager = new CertomancerConfigManager(new URL(\"http://localhost:9000/config\"));\nCertomancerContext c = manager.submitConfiguration(yamlConfig);\n```\n\nIn a Cucumber rule, that might look like this:\n\n```java\n    public static final String CERTOMANCER_URL = \"http://localhost:9000/config\";\n\n    @Given(\"^a Certomancer architecture defined by '(.*)'$\")\n    public void setCertomancerPKI(String configFile) throws IOException {\n        Path configPath = Paths.get(srcFolder, \"certomancer\", configFile);\n        String yamlConfig = new String(Files.readAllBytes(configPath), Charsets.UTF_8);\n        CertomancerContext c = new CertomancerConfigManager(new URL(CERTOMANCER_URL)).submitConfiguration(yamlConfig);\n        context.set(\"certomancerContext\", c);\n    }\n```\n\nThe `CertomancerContext` API is pretty straightforward: the `get()` method retrieves a `CertPackage` object containing a certificate, the corresponding private key and a list of other relevant certificates (a possible chain of trust, which may or may not be in the right order).\n\nIf you're looking to use this tool in JUnit tests, read on.\n\n\n### JUnit 4 integration\n\nIf you ever want to use Certomancer in JUnit tests, add the `certomancer-junit` module as a dependency.\nThis module adds another layer of convenience by defining a JUnit rule to load a Certomancer config for an entire test class.\nSince tests relying on Certomancer won't run without a Certomancer container available, this rule handles both resource provisioning and automatic skipping of tests if Certomancer is not configured.\n\n```java\npublic class SomeTest {\n    @ClassRule\n    public static final CertomancerResource CERTOMANCER = new CertomancerResource(\"typical-ocsp-scenario.yml\");\n\n    // tests go here\n}\n\n```\nUse `CERTOMANCER.getContext()` to get access to the `CertomancerContext`.\n\nThis JUnit rule loads test scenarios from the classpath (the above invocation would look for a resource named `certomancer/typical-ocsp-scenario.yml`).\n\nThe configuration URL to use is read off from the `CERTOMANCER_CONFIG_URL` environment variable. Tests that depend on a `CertomancerResource` will be ignored if said environment variable is not set.\n\n## Disclaimer\n\nThis is an experimental tool, not an iText product. It is provided to the\ncommunity under the terms of the MIT license (see [LICENSE](LICENSE)) on an\nas-is basis.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitext%2Fcertomancer-as-a-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitext%2Fcertomancer-as-a-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitext%2Fcertomancer-as-a-service/lists"}