Confidential Computing 비밀

CoCo 비밀 주입과 efi_secret

이 문서는 Confidential Computing 환경에서 firmware가 운영체제로 비밀을 전달하는 과정을 EFI driver와 `efi_secret` kernel module을 중심으로 설명한다.

AMD SEV(Secure Encrypted Virtualization) 같은 Confidential Computing(CoCo) hardware는 host나 hypervisor가 읽을 수 없도록 Guest Owner가 VM memory에 secret을 주입하게 한다. SEV에서는 guest 실행이 시작되기 전 VM launch 초기 단계에서 secret injection을 수행한다. `efi_secret` module은 사용자 공간 응용 프로그램이 securityfs를 통해 이러한 secret에 접근하도록 한다.

.. SPDX-License-Identifier: GPL-2.0

==============================
Confidential Computing secrets
==============================

This document describes how Confidential Computing secret injection is handled
from the firmware to the operating system, in the EFI driver and the efi_secret
kernel module.


Introduction
============

Confidential Computing (coco) hardware such as AMD SEV (Secure Encrypted
Virtualization) allows guest owners to inject secrets into the VMs
memory without the host/hypervisor being able to read them.  In SEV,
secret injection is performed early in the VM launch process, before the
guest starts running.

The efi_secret kernel module allows userspace applications to access these
secrets via securityfs.

EFI secret area의 데이터 흐름

guest firmware는 secret injection용 memory 영역을 예약하고 base GPA와 길이를 EFI configuration table의 `LINUX_EFI_COCO_SECRET_AREA_GUID` 항목으로 공개할 수 있다. GUID 값은 `adf956ad-e98c-484c-ae11-b51c7d336447`이다. firmware는 이 영역을 `EFI_RESERVED_TYPE`으로 표시해야 하며 커널은 자신의 용도로 사용하지 않아야 한다.

VM launch 중 virtual machine manager는 이 영역에 secret을 주입할 수 있다. AMD SEV와 SEV-ES는 `KVM_SEV_LAUNCH_SECRET` 명령을 사용한다. Guest Owner secret 데이터는 GUID로 구분된 secret value table이어야 하며 정확한 binary 형식은 `drivers/virt/coco/efi_secret/efi_secret.c`의 ‘Structure of the EFI secret area’에 정의되어 있다.

커널 시작 시 EFI driver는 configuration table에서 얻은 secret area 위치를 `efi.coco_secret`에 저장한다. 이후 영역을 mapping하고 첫 내용이 `EFI_SECRET_TABLE_HEADER_GUID`(`1e74f542-71dd-4d66-963e-ef4287ff173b`)인지 검사해 데이터 존재 여부를 판단한다. 내용이 있으면 `efi_secret` module을 자동 적재하여 securityfs로 공개한다. 파일시스템 ABI는 `Documentation/ABI/testing/securityfs-secrets-coco`에 있다.

Secret data flow
================

The guest firmware may reserve a designated memory area for secret injection,
and publish its location (base GPA and length) in the EFI configuration table
under a ``LINUX_EFI_COCO_SECRET_AREA_GUID`` entry
(``adf956ad-e98c-484c-ae11-b51c7d336447``).  This memory area should be marked
by the firmware as ``EFI_RESERVED_TYPE``, and therefore the kernel should not
be use it for its own purposes.

During the VM's launch, the virtual machine manager may inject a secret to that
area.  In AMD SEV and SEV-ES this is performed using the
``KVM_SEV_LAUNCH_SECRET`` command (see [sev]_).  The structure of the injected
Guest Owner secret data should be a GUIDed table of secret values; the binary
format is described in ``drivers/virt/coco/efi_secret/efi_secret.c`` under
"Structure of the EFI secret area".

On kernel start, the kernel's EFI driver saves the location of the secret area
(taken from the EFI configuration table) in the ``efi.coco_secret`` field.
Later it checks if the secret area is populated: it maps the area and checks
whether its content begins with ``EFI_SECRET_TABLE_HEADER_GUID``
(``1e74f542-71dd-4d66-963e-ef4287ff173b``).  If the secret area is populated,
the EFI driver will autoload the efi_secret kernel module, which exposes the
secrets to userspace applications via securityfs.  The details of the
efi_secret filesystem interface are in [secrets-coco-abi]_.

암호화 파일 응용 예제

예제 guest는 암호화된 파일을 대상으로 계산한다. Guest Owner가 secret injection으로 복호화 key를 제공하면 guest application이 `efi_secret` filesystem에서 이를 읽고 파일을 memory로 복호화한 뒤 필요한 계산을 수행한다.

host는 disk image의 파일이 암호화되어 있어 원본을 읽지 못하고, secret이 secure channel로 전달되므로 복호화 key도 읽지 못한다. 또한 guest memory 자체가 암호화된 confidential guest이므로 memory 속 복호화 내용도 읽지 못한다.

launch 때 네 secret이 주입된 예제에서 `/sys/kernel/security/secrets/coco`를 나열하면 각 secret이 GUID 이름의 읽기 전용 파일로 나타난다. `hd`로 파일 내용을 읽을 수 있으며, 예제 데이터는 `these-are-the-kata-secrets`와 뒤따르는 binary byte를 포함한다. 파일을 `rm`하면 해당 secret entry가 사라지고 나머지 세 항목만 남는다. 원문의 전체 명령과 hex dump는 그대로 보존한다.

Application usage example
=========================

Consider a guest performing computations on encrypted files.  The Guest Owner
provides the decryption key (= secret) using the secret injection mechanism.
The guest application reads the secret from the efi_secret filesystem and
proceeds to decrypt the files into memory and then performs the needed
computations on the content.

In this example, the host can't read the files from the disk image
because they are encrypted.  Host can't read the decryption key because
it is passed using the secret injection mechanism (= secure channel).
Host can't read the decrypted content from memory because it's a
confidential (memory-encrypted) guest.

Here is a simple example for usage of the efi_secret module in a guest
to which an EFI secret area with 4 secrets was injected during launch::

        # ls -la /sys/kernel/security/secrets/coco
        total 0
        drwxr-xr-x 2 root root 0 Jun 28 11:54 .
        drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
        -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
        -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
        -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2
        -r--r----- 1 root root 0 Jun 28 11:54 e6f5a162-d67f-4750-a67c-5d065f2a9910

        # hd /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910
        00000000  74 68 65 73 65 2d 61 72  65 2d 74 68 65 2d 6b 61  |these-are-the-ka|
        00000010  74 61 2d 73 65 63 72 65  74 73 00 01 02 03 04 05  |ta-secrets......|
        00000020  06 07                                             |..|
        00000022

        # rm /sys/kernel/security/secrets/coco/e6f5a162-d67f-4750-a67c-5d065f2a9910

        # ls -la /sys/kernel/security/secrets/coco
        total 0
        drwxr-xr-x 2 root root 0 Jun 28 11:55 .
        drwxr-xr-x 3 root root 0 Jun 28 11:54 ..
        -r--r----- 1 root root 0 Jun 28 11:54 736870e5-84f0-4973-92ec-06879ce3da0b
        -r--r----- 1 root root 0 Jun 28 11:54 83c83f7f-1356-4975-8b7e-d3a0b54312c6
        -r--r----- 1 root root 0 Jun 28 11:54 9553f55d-3da2-43ee-ab5d-ff17f78864d2

관련 ABI와 SEV 사양

SEV `LAUNCH_SECRET` 연산의 세부 사항은 AMD SEV Key Management API specification을 참조한다. 커널 구현 배경은 `Documentation/virt/kvm/x86/amd-memory-encryption.rst`, securityfs ABI는 `Documentation/ABI/testing/securityfs-secrets-coco`, 외부 사양은 AMD 문서 `55766_SEV-KM_API_Specification.pdf`에 연결된다.

References
==========

See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation.

.. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst
.. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco
.. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf