1*4882a593SmuzhiyunWhat: security/evm 2*4882a593SmuzhiyunDate: March 2011 3*4882a593SmuzhiyunContact: Mimi Zohar <zohar@us.ibm.com> 4*4882a593SmuzhiyunDescription: 5*4882a593Smuzhiyun EVM protects a file's security extended attributes(xattrs) 6*4882a593Smuzhiyun against integrity attacks. The initial method maintains an 7*4882a593Smuzhiyun HMAC-sha1 value across the extended attributes, storing the 8*4882a593Smuzhiyun value as the extended attribute 'security.evm'. 9*4882a593Smuzhiyun 10*4882a593Smuzhiyun EVM supports two classes of security.evm. The first is 11*4882a593Smuzhiyun an HMAC-sha1 generated locally with a 12*4882a593Smuzhiyun trusted/encrypted key stored in the Kernel Key 13*4882a593Smuzhiyun Retention System. The second is a digital signature 14*4882a593Smuzhiyun generated either locally or remotely using an 15*4882a593Smuzhiyun asymmetric key. These keys are loaded onto root's 16*4882a593Smuzhiyun keyring using keyctl, and EVM is then enabled by 17*4882a593Smuzhiyun echoing a value to <securityfs>/evm made up of the 18*4882a593Smuzhiyun following bits: 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun === ================================================== 21*4882a593Smuzhiyun Bit Effect 22*4882a593Smuzhiyun === ================================================== 23*4882a593Smuzhiyun 0 Enable HMAC validation and creation 24*4882a593Smuzhiyun 1 Enable digital signature validation 25*4882a593Smuzhiyun 2 Permit modification of EVM-protected metadata at 26*4882a593Smuzhiyun runtime. Not supported if HMAC validation and 27*4882a593Smuzhiyun creation is enabled. 28*4882a593Smuzhiyun 31 Disable further runtime modification of EVM policy 29*4882a593Smuzhiyun === ================================================== 30*4882a593Smuzhiyun 31*4882a593Smuzhiyun For example:: 32*4882a593Smuzhiyun 33*4882a593Smuzhiyun echo 1 ><securityfs>/evm 34*4882a593Smuzhiyun 35*4882a593Smuzhiyun will enable HMAC validation and creation 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun :: 38*4882a593Smuzhiyun 39*4882a593Smuzhiyun echo 0x80000003 ><securityfs>/evm 40*4882a593Smuzhiyun 41*4882a593Smuzhiyun will enable HMAC and digital signature validation and 42*4882a593Smuzhiyun HMAC creation and disable all further modification of policy. 43*4882a593Smuzhiyun 44*4882a593Smuzhiyun :: 45*4882a593Smuzhiyun 46*4882a593Smuzhiyun echo 0x80000006 ><securityfs>/evm 47*4882a593Smuzhiyun 48*4882a593Smuzhiyun will enable digital signature validation, permit 49*4882a593Smuzhiyun modification of EVM-protected metadata and 50*4882a593Smuzhiyun disable all further modification of policy 51*4882a593Smuzhiyun 52*4882a593Smuzhiyun Echoing a value is additive, the new value is added to the 53*4882a593Smuzhiyun existing initialization flags. 54*4882a593Smuzhiyun 55*4882a593Smuzhiyun For example, after:: 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun echo 2 ><securityfs>/evm 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun another echo can be performed:: 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun echo 1 ><securityfs>/evm 62*4882a593Smuzhiyun 63*4882a593Smuzhiyun and the resulting value will be 3. 64*4882a593Smuzhiyun 65*4882a593Smuzhiyun Note that once an HMAC key has been loaded, it will no longer 66*4882a593Smuzhiyun be possible to enable metadata modification. Signaling that an 67*4882a593Smuzhiyun HMAC key has been loaded will clear the corresponding flag. 68*4882a593Smuzhiyun For example, if the current value is 6 (2 and 4 set):: 69*4882a593Smuzhiyun 70*4882a593Smuzhiyun echo 1 ><securityfs>/evm 71*4882a593Smuzhiyun 72*4882a593Smuzhiyun will set the new value to 3 (4 cleared). 73*4882a593Smuzhiyun 74*4882a593Smuzhiyun Loading an HMAC key is the only way to disable metadata 75*4882a593Smuzhiyun modification. 76*4882a593Smuzhiyun 77*4882a593Smuzhiyun Until key loading has been signaled EVM can not create 78*4882a593Smuzhiyun or validate the 'security.evm' xattr, but returns 79*4882a593Smuzhiyun INTEGRITY_UNKNOWN. Loading keys and signaling EVM 80*4882a593Smuzhiyun should be done as early as possible. Normally this is 81*4882a593Smuzhiyun done in the initramfs, which has already been measured 82*4882a593Smuzhiyun as part of the trusted boot. For more information on 83*4882a593Smuzhiyun creating and loading existing trusted/encrypted keys, 84*4882a593Smuzhiyun refer to: 85*4882a593Smuzhiyun Documentation/security/keys/trusted-encrypted.rst. Both 86*4882a593Smuzhiyun dracut (via 97masterkey and 98integrity) and systemd (via 87*4882a593Smuzhiyun core/ima-setup) have support for loading keys at boot 88*4882a593Smuzhiyun time. 89*4882a593Smuzhiyun 90*4882a593SmuzhiyunWhat: security/integrity/evm/evm_xattrs 91*4882a593SmuzhiyunDate: April 2018 92*4882a593SmuzhiyunContact: Matthew Garrett <mjg59@google.com> 93*4882a593SmuzhiyunDescription: 94*4882a593Smuzhiyun Shows the set of extended attributes used to calculate or 95*4882a593Smuzhiyun validate the EVM signature, and allows additional attributes 96*4882a593Smuzhiyun to be added at runtime. Any signatures generated after 97*4882a593Smuzhiyun additional attributes are added (and on files possessing those 98*4882a593Smuzhiyun additional attributes) will only be valid if the same 99*4882a593Smuzhiyun additional attributes are configured on system boot. Writing 100*4882a593Smuzhiyun a single period (.) will lock the xattr list from any further 101*4882a593Smuzhiyun modification. 102