{"id":13641707,"url":"https://github.com/intel/trusted-certificate-issuer","last_synced_at":"2025-04-20T11:31:48.506Z","repository":{"id":38298494,"uuid":"450659350","full_name":"intel/trusted-certificate-issuer","owner":"intel","description":"Trusted Certificate Service (TCS) is a K8s service to protect signing keys using Intel's SGX technology. K8s CSR and cert-manager CR APIs are both supported. TCS also contains integration samples for Istio service mesh and Key Management Reference Application (KMRA).","archived":false,"fork":false,"pushed_at":"2024-04-30T06:10:12.000Z","size":896,"stargazers_count":29,"open_issues_count":11,"forks_count":15,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-08-09T00:28:11.669Z","etag":null,"topics":["certificate","istio","kubernetes","private-key-infrastructure","sgx"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intel.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-21T22:37:25.000Z","updated_at":"2024-07-15T22:00:56.000Z","dependencies_parsed_at":"2024-06-18T20:11:58.275Z","dependency_job_id":null,"html_url":"https://github.com/intel/trusted-certificate-issuer","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intel%2Ftrusted-certificate-issuer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intel%2Ftrusted-certificate-issuer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intel%2Ftrusted-certificate-issuer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intel%2Ftrusted-certificate-issuer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intel","download_url":"https://codeload.github.com/intel/trusted-certificate-issuer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223827570,"owners_count":17209805,"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":["certificate","istio","kubernetes","private-key-infrastructure","sgx"],"created_at":"2024-08-02T01:01:23.307Z","updated_at":"2024-11-09T12:30:53.052Z","avatar_url":"https://github.com/intel.png","language":"Go","funding_links":[],"categories":["Key and Password Management"],"sub_categories":["Library OSes and SDKs"],"readme":"# Trusted Certificate Service for Kubernetes Platform\n\u003c!-- Table of contents is auto generated using \n[Auto Markdown TOC](https://marketplace.visualstudio.com/items?itemName=huntertran.auto-markdown-toc) extension --\u003e\n\u003c!-- TOC depthfrom:2 depthto:3 --\u003e\n\n- [Overview](#overview)\n- [Getting started](#getting-started)\n    - [Prerequisites](#prerequisites)\n    - [Installing with Helm](#installing-with-helm)\n    - [Installing with source code](#installing-with-source-code)\n    - [Create an Issuer](#create-an-issuer)\n    - [Create certificates](#create-certificates)\n- [Deployment in Azure](#deployment-in-azure)\n- [Sample use cases](#sample-use-cases)\n- [Limitations](#limitations)\n\n\u003c!-- /TOC --\u003e\n\n## Overview\n\n\u003c!-- TODO: Review and rephrase this section --\u003e\nTrusted Certificate Service (TCS) is a Kubernetes certificate signing solution\nthat uses the security capabilities provided by Intel® Software Guard Extensions\n(Intel® SGX). The signing key is stored and used inside the Intel SGX enclave(s)\nand is never stored in clear anywhere in the system. TCS is implemented as a\n[cert-manager external issuer](https://cert-manager.io/docs/configuration/external/)\nby providing support for both cert-manager and kubernetes certificate signing APIs.\n\n## Getting started\n\nAll the examples in this page are using self-signed CA certificates. If you are\nlooking for more advanced use cases (e.g., Istio integration) please check the\n[sample use cases](#sample-use-cases).\n\n### Prerequisites\n\nPrerequisites for building and running Trusted Certificate Service:\n\n- Kubernetes cluster with one or more nodes with Intel® [SGX](https://software.intel.com/content/www/us/en/develop/topics/software-guard-extensions.html) supported hardware\n- [Intel® SGX device plugin](https://github.com/intel/intel-device-plugins-for-kubernetes/blob/main/cmd/sgx_plugin/README.md) for Kubernetes\n- [Intel® SGX AESM daemon](https://github.com/intel/linux-sgx#install-the-intelr-sgx-psw)\n- [cert-manager](https://cert-manager.io/next-docs/installation/). The `cmctl` is also used later in the examples so you may want to install it also.\n- Linux kernel version 5.11 or later on the host (in tree Intel SGX driver)\n- git, or similar tool, to obtain the source code\n- Docker, or similar tool, to build container images\n- Container registry ([local](https://docs.docker.com/registry/deploying/) or remote)\n\n### Installing with Helm \n\nIf you want to use Helm to install TCS see the document [here](https://github.com/intel/helm-charts/tree/main/charts/trusted-certificate-issuer).\n\n### Installing with source code\n\nThis section covers how to obtain the source code, build and install it.\n\n1. Getting the source code\n\n```sh\ngit clone https://github.com/intel/trusted-certificate-issuer.git\n```\n2. Build and push the container image\n\nChoose a container registry to push the generated image using `REGISTRY` make variable.\nThe registry should be reachable from the Kubernetes cluster.\n\n\u003e **NOTE**: By default, the enclave signing is done using a private key\nauto-generated by the TCS issuer. In case, if you want to integrate your\nown signing tool, modify/replace the `enclave-config/sign-enclave.sh`\nscript accordingly before building the docker image.\nRefer to [Intel(R) SGX SDK developer reference](https://download.01.org/intel-sgx/linux-2.1.3/docs/Intel_SGX_Developer_Reference_Linux_2.1.3_Open_Source.pdf) for more details about enclave signing.\n\n```sh\n$ cd trusted-certificate-issuer\n$ export REGISTRY=\"localhost:5000\" # docker registry to push the container image\n$ make docker-build\n$ make docker-push\n```\n\u003e **NOTE**: If you operate behind a corporate proxy, proxy settings can be passed in like \\\n```make docker-build BUILD_ARGS=\"--build-arg http_proxy=someproxy --build-arg https_proxy=someproxy --build-arg no_proxy=some_list\"```\n3. Deploy custom resource definitions (CRDs)\n\n```sh\n# set the KUBECONFIG based on your configuration\nexport KUBECONFIG=\"$HOME/.kube/config\"\nmake install # Install CRDs\n```\n\n4. Make the deployment\n\n```sh\nmake deploy\n```\n\nBy default, `tcs-issuer` namespace is used for the deployment.\n```sh\n# Ensure that the pod is running state\n$ kubectl get po -n tcs-issuer\nNAME                              READY   STATUS    RESTARTS   AGE\ntcs-controller-5dd5c46b44-4nz9f   1/1     Running   0          30m\n```\n\n### Create an Issuer\n\nOnce the deployment is up and running, you are ready to provision TCS\nissuer(s) using either a namespace-scoped `TCSIssuer` or a\ncluster-scoped `TCSClusterIssuer` resource.\n\nThe example below creates a TCS issuer named `my-ca` for `sandbox` namespace:\n\n```sh\nkubectl create ns sandbox\ncat \u003c\u003cEOF |kubectl create -f -\napiVersion: tcs.intel.com/v1alpha1\nkind: TCSIssuer\nmetadata:\n    name: my-ca\n    namespace: sandbox\nspec:\n    secretName: my-ca-cert\nEOF\n```\n\nSuccessful deployment looks like this:\n\n```sh\n$ kubectl get tcsissuers -n sandbox\nNAME    AGE    READY   REASON      MESSAGE\nmy-ca   2m     True    Reconcile   Success\n\n$ kubectl get secret my-ca-cert -n sandbox\nNAME                  TYPE                                  DATA   AGE\nmy-ca-cert            kubernetes.io/tls                     2      3h14m\n```\n\nThe above issuer creates and stores it's private key inside the Intel\nSGX enclave and the root certificate is saved as a Kubernetes Secret with name\nspecified with `spec.secretName`, under the issuer's namespace.\n\nTypically the issuer secret (`my-ca-cert` in our case) contains both the\ncertificate and the private key. But in the Trusted Certificate Service case, the\nprivate key is empty since they key is stored and used inside a Intel SGX\nenclave. You can verify the empty private key in the secret with the following\ncommand:\n\n```sh\nkubectl get secrets -n sandbox my-ca-cert -o jsonpath='{.data.tls\\.key}'\n```\n\n\u003cimg src=\"docs/images/tcs-kubernetes.png\" alt=\"drawing\" width=\"50%\"/\u003e\n\nFigure 1: Trusted Certificate Install\n\n1. The `TCSIssuer` is created.\n1. This automatically creates the `my-ca-cert` secret. The `tls.key` field is blank\nbecause the private key is actually created and stored within a Intel SGX enclave.\n\nBelow is a demo of the install process.\n\n\u003ca href=\"https://asciinema.org/a/509919\"\u003e\u003cimg src=\"https://asciinema.org/a/509919.svg\" width=\"60%\"/\u003e\u003c/a\u003e\n\n### Create certificates\n\nCreating and signing certificates can be done by using cert-manager `Certificate` \nor Kubernetes `CertificateSigningRequest` APIs.\n\n#### Using cert-manager Certificate\n\nThis example shows how to request X509 certificate signed by the Trusted Certificate Service\nusing cert-manger `Certificate` API. Create a cert-manager `Certificate` object and\nset the `spec.issuerRef` to `TCSIssuer`(or `TCSClusterIssuer`).\n\n```sh\ncat \u003c\u003cEOF |kubectl create -f -\napiVersion: cert-manager.io/v1\nkind: Certificate\nmetadata:\n  name: my-certificate\n  namespace: sandbox\nspec:\n  # The secret name to store the signed certificate\n  secretName: demo-cert-tls\n  # Common Name\n  commonName: intel.sgx.demo\n  # Ensure the issuerRef is set to the right issuer\n  issuerRef:\n    group: tcs.intel.com # TCS issuer API group\n    kind: TCSIssuer      # Configured issuer type\n    name: my-ca          # Configured issuer name\nEOF\n```\n\nThe cert-manager creates a corresponding `CertificateRequest` for the\n`Certificate` above. One has to approve the `CertificateRequest` so that\nthe TCS controller can sign the request in the next reconcile loop.\n\n```sh\n$ kubectl get certificaterequest -n sandbox\nNAME                   APPROVED   DENIED   READY   ISSUER   REQUESTOR                                         AGE\nmy-certificate-nljcz   False               False   my-ca    system:serviceaccount:cert-manager:cert-manager   1m\n```\n\nPrivileged user needs to approve the `CertificateRequest` with the cert-manager's `cmctl` utility:\n\n```sh\n$ cmctl approve my-certificate-nljcz -n sandbox\n```\n\nCheck if the certificate is exported to the secret referenced in\nthe `spec.secretName`.\n\n```sh\n$ kubectl get certificates,secret -n sandbox\nNAME                                         READY   SECRET          AGE\ncertificate.cert-manager.io/my-certificate   True    demo-cert-tls   2m1s\n\nNAME                         TYPE                                  DATA   AGE\nsecret/default-token-69dv6   kubernetes.io/service-account-token   3      3h15m\nsecret/demo-cert-tls         kubernetes.io/tls                     2      2m1s\nsecret/my-ca-cert            kubernetes.io/tls                     2      3h14m\n```\n\n\u003cimg src=\"docs/images/tcs-kubernetes-certmanager.png\" alt=\"drawing\" width=\"60%\"/\u003e\n\nFigure 2: Trusted Certificate Issuer with cert-manager\n\n1. The `TCSIssuer` is created.\n1. This automatically creates the `my-ca-cert` secret.\n1. A user creates a `Certificate` object specifying to use the TCS Issuer.\n1. cert-manager automatically creates a `CertificateRequests` object.\n1. A user approves the `CertificateRequests` object.\n1. The TCS Controller then takes the request and signs the certificate inside\nthe Intel SGX enclave using the private key stored within that enclave.\n1. The signed certificate is then copied into the `demo-cert-tls` secret that was\nspecified in the original `Certificate` object.\n1. Finally, that same signed certificate is copied back into the `CertificateRequests`\nobject.\n\nBelow is a demo of this working with cert-manager.\n\n\u003ca href=\"https://asciinema.org/a/509920\"\u003e\u003cimg src=\"https://asciinema.org/a/509920.svg\" width=\"60%\"/\u003e\u003c/a\u003e\n\n#### Using Kubernetes CSR\n\nThis example shows how to request an X509 certificate signed by the Trusted Certificate Service\nusing Kubernetes CSR.\n\nFirst, generate a PEM encoded private key (`privkey.pem`) and certificate signing request (`csr.pem`)\nusing `openssl` tool:\n\n```sh\n$ openssl req -new -nodes -newkey rsa:3072 -keyout privkey.pem -out ./csr.pem -subj \"/O=Foo Company/CN=foo.bar.com\"\n```\n\nCreate a Kubernetes `CertificateSigningRequest` using the csr (`csr.pem`) generated above.\nThe `spec.signerName` field must refer to the TCS issuer we configured earlier\nin the form of `\u003cissuer-type\u003e.\u003cissuer-group\u003e/\u003cissuer-namespace\u003e.\u003cissuer-name\u003e`.\nIn this example the signer name is `tcsissuer.tcs.intel.com/sandbox.my-ca`.\n\n**Note:** the issuer namespace in the case of `tcsclusterissuer` is the namespace\nof the Trusted Certificate Service.\n\n```sh\ncat \u003c\u003cEOF |kubectl apply -f -\napiVersion: certificates.k8s.io/v1\nkind: CertificateSigningRequest\nmetadata:\n  name: test-csr\nspec:\n  groups:\n  - system:authenticated\n  request: $(cat csr.pem | base64 | tr -d '\\n')\n  signerName: tcsissuer.tcs.intel.com/sandbox.my-ca\n  usages:\n  - client auth\nEOF\n```\n\nNow the `test-csr` is the in pending state waiting for approval.\n\n```sh\n$ kubectl get certificatesigningrequests\nNAME       AGE   SIGNERNAME                              REQUESTOR          CONDITION\ntest-csr   46s   tcsissuer.tcs.intel.com/sandbox.my-ca   kubernetes-admin   Pending\n````\n\nPrivileged user needs to approve the `test-csr` with the following command:\n\n```sh\n# Approve the CSR so the TCS controller generates the certificate\nkubectl certificate approve test-csr\n```\nOnce the request is approved, the Trusted Certificate Service signs it. At this\npoint the CSR contains the requested certificate signed by the CA using the\nprivate key stored inside the Intel SGX enclave.\n\nYou can examine the CSR with the following command:\n\n```sh\n$ kubectl describe csr\n\nName:         test-csr\nLabels:       \u003cnone\u003e\nAnnotations:  kubectl.kubernetes.io/last-applied-configuration={\"apiVersion\":\"certificates.k8s.io/v1\",\"kind\":\"CertificateSigningRequest\",\"metadata\":{\"annotations\":{},\"name\":\"test-csr\"},\"spec\":{\"groups\":[\"system:authenticated\"],\"request\":\"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJRGNUQ0NBZGtDQVFBd0xERVVNQklHQTFVRUNnd0xSbTl2SUVOdmJXRndibmt4RkRBU0JnTlZCQU1NQzJadgpieTVpWVhJdVkyOXRNSUlCb2pBTkJna3Foa2lHOXcwQkFRRUZBQU9DQVk4QU1JSUJpZ0tDQVlFQTZhNzkvTmZLCmdrYzQ5dXd6TVFUajBwZzhuZjZ3VU5tcmNVaG5IUDNhUitDYjZKcE0wOVF3RHBmblI2VU13ejZFVy9RSis3WVQKMndLUFJTRVZqZ3owT29NdXh0c0tScGN2VCtWaDZkb3JjSkU0ZTdjQ2FWK1ZKN0pQRGtwYzdFNSt6VCtncVlRKwptMWhjS0FmTEk0VEpZNzJZR2MzTWt5QkVqRzNsKzl3emxHNVlpZEduYVFjNDhMNUJQSXFxOEdKelpWSTkvQWxLClVDVjcwM2pGQnpKdTBEbFpTQWd2WEo1RUhNbWVhaFBQYTFOV2dkM29mQ2FUcTlnM0xaSTBDejdWbndOK0l1bzEKNGpRcE1zNzVQTFZVUTQ2SEZ0YUxJTWZPNDlkZk94SUwwNlkwZG1XNUc0R05zNUR4SkhtYm11QlQ1NGMrUm5MUQoyVldJL2VRS2xQQW5Sdk00SmpEM3hEcENvOGViSE9nS2RsRU9MTkFPTEk0L2VMUG1GcXlTUGxuY2RTZlFqc2UvCkJQOEpuQk9Xa0xpSUZ4bzBwT1lrTUFDaHhWdDJkdURLcldRZm1JSkhUUSs0Q05OZjhlanZOZkZCY0pmNllldHUKRnlkNnA4WmwrYkV2TldYbDBKeGNQNWlFVGFYWkZqblJqMWxzZWVSbWo3OGFyRDZCUkhTTFlsM0pBZ01CQUFHZwpBREFOQmdrcWhraUc5dzBCQVFzRkFBT0NBWUVBMXYrOURlUE5XOER6Z2twVzBhU1czdW1xR05xc05zaWNhQjc1Cjc3UGsyRnNBMTMya2JWTXBBY2NCRzc1WGh4T0VkNFNYdTJ0eVI1MGxOMUpaNnJldzY5b1dUYWZTTTVXNm00RFAKcE1tVjRJbTJiajlUTUhYeHdXVjdXVk5JL2dQK1BFRDVROVJMNy82Sjh2VnV5aFhZaTAyc2NkampKaStIT0M4Ywo1TFpLem5TQUhtcmZEVGlveG5ydUNqY1ZEZlFlSGlJMkw1SW94aXAwUmt5L0Y1UkhwTjRyMHFQS25Na2F3enRYClV3alB6Nk9uWGVPK1EvVGZyRm5ka2V3OCtsSFc2akxneXNUNlU3SjdmdjVuL1lSUXdYSHJadi9LNFVneW9zU3oKZy9PSkZoOVpyWjl6WFBhT01sN1pLYnlUUXE2NGtMSmFEQys0eWIycXlUT1hMUm1xK0Y1MWc2a0tJdDdMWXdtMQpjR0N3WTc2WmFHMm9hVkQxRVNQSWtpc0I4U01ncVNEajlhQjFxRDJ0Y1E4RGxoV1o3dEdDd3M5VC9RUDlvQnpsCjc5S0g3Qnc1QnVSVFlRT0srMTdJSWUrNUx0YVFzS1dpczBsaGtvQ1R3TjdUS2FnQ1dLWWk0RE16em1wVlNvbTEKaVphb21nUDJIKy8yQ3RoOUNJN1dwVWR5WklkQgotLS0tLUVORCBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0K\",\"signerName\":\"tcsissuer.tcs.intel.com/sandbox.my-ca\",\"usages\":[\"client auth\"]}}\n\nCreationTimestamp:  Mon, 24 Jan 2022 16:11:10 +0200\nRequesting User:    kubernetes-admin\nSigner:             tcsissuer.tcs.intel.com/sandbox.my-ca\nStatus:             Approved,Issued\nSubject:\n         Common Name:    foo.bar.com\n         Serial Number:  \n         Organization:   Foo Company\n```\n\u003cimg src=\"docs/images/tcs-kubernetes-csr.png\" alt=\"drawing\" width=\"60%\"/\u003e\n\nFigure 3: Trusted Certificate Issuer with Kubernetes CSR\n\n1. The `TCSIssuer` is created.\n1. This automatically creates the `my-ca-cert` secret.\n1. A user creates a certificate signing request using openssl and saving the\nprivate key. Using that `csr.pem` file, a `CertificateSigningRequest` object is\ncreated in Kubernetes.\n1. A user approves the `CertificateSigningRequest` object.\n1. The TCS Controller then takes the request and signs the certificate inside\nthe Intel SGX enclave using the private key stored within that enclave.\n1. The signed certificate is then copied back into the original `CertificateSigningRequest`\nobject into the `certificate` field.\n\nBelow is a demo of this working with Kubernetes CSR.\n\n\u003ca href=\"https://asciinema.org/a/509921\"\u003e\u003cimg src=\"https://asciinema.org/a/509921.svg\" width=\"60%\"/\u003e\u003c/a\u003e\n\n## Deployment in Azure\n\nYou can deploy TCS also in Azure by following the instructions [here](./docs/azure.md).\n## Sample use cases\n\nRefer to more example use cases related to Istio service mesh and Trusted Certificate Service\n\n- [Istio custom CA integration using Kubernetes CSR](./docs/istio-custom-ca-with-csr.md)\n- [Istio integration with cert-manager and istio-csr](./docs/istio-csr-external-ca-setup.md)\n- [Remote attestation and key management (manual)](./docs/integrate-key-server.md)\n## Limitations\n\n- This version of the software is pre-production release and is meant for evaluation and trial purposes only.\n- The certificate authority (CA) private key transport method (via QuoteAttestation custom resource) does not guarantee any authenticity, only confidentiality, and therefore cannot protect from attacks like key substitution or key replay.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintel%2Ftrusted-certificate-issuer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintel%2Ftrusted-certificate-issuer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintel%2Ftrusted-certificate-issuer/lists"}