1.. SPDX-License-Identifier: GPL-2.0 2 3================================== 4IMA Measurements Export and Delete 5================================== 6 7 8Introduction 9============ 10 11The IMA measurements list is currently stored in the kernel memory. Memory 12occupation grows linearly with the number of records, and can become a 13problem especially in environments with reduced resources. 14 15While there is an advantage in keeping the IMA measurements list in kernel 16memory, so that it is always available for reading from the securityfs 17interfaces, storing it elsewhere would make it possible to free precious 18memory for other kernel usage. 19 20The IMA measurements list needs to be retained and safely stored for new 21attestation servers to validate it. Assuming the IMA measurements list is 22properly saved, storing it outside the kernel does not introduce security 23issues, since its integrity is anyway protected by the TPM. 24 25Hence, the new IMA staging mechanism is introduced to export IMA 26measurements to user space and delete them from kernel space. 27 28Staging consists in atomically moving the current measurements list to a 29temporary list, so that measurements can be deleted afterwards. The staging 30operation locks the hot path (racing with addition of new measurements) for 31a very short time, only for swapping the list pointers. Deletion of the 32measurements instead is done locklessly, away from the hot path. 33 34There are two flavors of the staging mechanism. In the staging with prompt, 35all current measurements are staged, read and deleted upon confirmation. In 36the staging and deleting flavor, N measurements are staged from the 37beginning of the current measurements list and immediately deleted without 38confirmation. 39 40 41Management of Staged Measurements 42================================= 43 44Since with the staging mechanism measurement records are removed from the 45kernel, the staged measurements need to be saved in a storage and 46concatenated together, so that they can be presented during remote 47attestation as if staging was never done. This task can be accomplished by 48a remote attestation agent modified to support staging, or a system 49service. 50 51Coordination is necessary in the case where there are multiple actors 52requesting measurements to be staged. 53 54In the staging with prompt case, the measurement interfaces can be accessed 55only by one actor (writer) at a time, so the others will get an error until 56the former closes it. Since the actors don't care about N, when they gain 57access to the interface, they will get all the staged measurements at the 58time of their request. 59 60In the case of staging and deleting, coordination is more important, since 61there is the risk that two actors unaware of each other compute the value N 62on the current measurements list and request IMA to stage N twice. 63 64 65Remote Attestation Agent Workflow 66================================= 67 68Remote attestation agents can be configured to always present all the 69measurements to the remote verifiers or, alternatively, to only provide the 70measurements that have not been verified yet by the remote verifiers. 71 72In the latter case, determining which measurements need to be sent and 73verified must solely depend on the remote verifier. The remote attestation 74agent can proactively send partial measurements, at the condition that they 75are the ones that the remote verifier needs. 76 77An agent can rely on one of the supported staging methods to proactively 78send to a remote verifier the measurements since the previous request up 79to the ones that verify the TPM quote obtained in the current request. 80The workflow with each staging method is the following. 81 82With staging with prompt, the agent stages the current measurements list, 83reads and stores the measurements in a storage and immediately requests 84IMA to delete the staged measurements from kernel memory. Afterwards, it 85calculates N by replaying the PCR extend on the stored measurements until 86the calculated PCRs match the quoted PCRs. It then keeps the measurements 87in excess for the next attestation request. 88 89At the next attestation request, the agent performs the same steps above, 90and concatenates the new measurements to the ones in excess from the 91previous request. Also in this case, the agent replays the PCR extend until 92it matches the currently quoted PCRs, keeps the measurements in excess and 93presents the new N measurement records to the remote attestation server. 94 95With the staging and deleting method, the agent reads the current 96measurements list, calculates N and requests IMA to delete only those. The 97measurements in excess are kept in the IMA measurements list and can be 98retrieved at the next remote attestation request. 99 100While keeping only the excess measurements in the storage could be 101sufficient to serve the requests of a remote verifier, it is advised to 102keep all the obtained measurements locally, as they might be needed for the 103attestation with a different remote verifier. 104 105 106Usage 107===== 108 109The IMA staging mechanism can be enabled from the kernel configuration with 110the CONFIG_IMA_STAGING option. This option prevents inadvertently removing 111the IMA measurement list on systems which do not properly save it. 112 113If the option is enabled, IMA duplicates the current securityfs 114measurements interfaces (both binary and ASCII), by adding the ``_staged`` 115file suffix. Both the original and the staging interfaces gain the write 116permission for the root user and group, but require the process to have 117CAP_SYS_ADMIN set. 118 119The staging mechanism supports two flavors. 120 121 122Staging with prompt 123~~~~~~~~~~~~~~~~~~~ 124 125The current measurements list is moved to a temporary staging area, 126allowing it to be saved to external storage, before being deleted upon 127confirmation. 128 129This staging process is achieved with the following steps. 130 131 1. ``echo A > <_staged interface>``: the user requests IMA to stage the 132 entire measurements list; 133 2. ``cat <_staged interface>``: the user reads the staged measurements; 134 3. ``echo D > <_staged interface>``: the user requests IMA to delete 135 staged measurements. 136 137 138Staging and deleting 139~~~~~~~~~~~~~~~~~~~~ 140 141N measurements are staged to a temporary staging area, and immediately 142deleted without further confirmation. 143 144This staging process is achieved with the following steps. 145 146 1. ``cat <original interface>``: the user reads the current measurements 147 list and determines what the value N for staging should be; 148 2. ``echo N > <original interface>``: the user requests IMA to delete N 149 measurements from the current measurements list. 150 151 152Interface Access 153================ 154 155In order to avoid the IMA measurements list being suddenly truncated by the 156staging mechanism during a read, or having multiple concurrent staging, a 157semaphore-like locking scheme has been implemented on all the measurements 158list interfaces. 159 160Multiple readers can access concurrently the original and staged 161interfaces, and they can be in mutual exclusion with one writer. In order 162to see the same state across all the measurement interfaces, the same 163writer is allowed to open multiple interfaces for write or read/write. 164 165If an illegal access occurs, the open to the measurements list interface is 166denied. 167 168 169Kexec 170===== 171 172In the event a kexec() system call occurs between staging and deleting, the 173staged measurement records are marshalled before the current measurements 174list, so that they are both available when the secondary kernel starts. 175 176If measurement is suspended before requesting to delete staged or current 177measurements, IMA returns an error to user space to let it know that 178marshalling is already in progress, so that it does not save the 179measurements twice. 180 181IMA also disallows staging when suspending measurement, to avoid the 182situation where neither measurements are carried over to the secondary 183kernel, nor they are saved by user space to the storage. 184 185 186Hash table 187========== 188 189By default, the template digest of staged measurement records are kept in 190kernel memory (only template data are freed), to be able to detect 191duplicate records independently of staging. 192 193The new kernel option ``ima_flush_htable`` has been introduced to 194explicitly request a complete deletion of the staged measurements, for 195maximum kernel memory saving. If the option has been specified, duplicate 196records are still avoided on records of the current measurements list, 197but there can be duplicates between different groups of staged 198measurements. 199 200Flushing the hash table is supported only for the staging with prompt 201flavor. For the staging and deleting flavor, it would have been necessary 202to lock the hot path adding new measurements for the time needed to remove 203each selected measurement individually. 204