1*4882a593Smuzhiyun================================== 2*4882a593SmuzhiyunDigital Signature Verification API 3*4882a593Smuzhiyun================================== 4*4882a593Smuzhiyun 5*4882a593Smuzhiyun:Author: Dmitry Kasatkin 6*4882a593Smuzhiyun:Date: 06.10.2011 7*4882a593Smuzhiyun 8*4882a593Smuzhiyun 9*4882a593Smuzhiyun.. CONTENTS 10*4882a593Smuzhiyun 11*4882a593Smuzhiyun 1. Introduction 12*4882a593Smuzhiyun 2. API 13*4882a593Smuzhiyun 3. User-space utilities 14*4882a593Smuzhiyun 15*4882a593Smuzhiyun 16*4882a593SmuzhiyunIntroduction 17*4882a593Smuzhiyun============ 18*4882a593Smuzhiyun 19*4882a593SmuzhiyunDigital signature verification API provides a method to verify digital signature. 20*4882a593SmuzhiyunCurrently digital signatures are used by the IMA/EVM integrity protection subsystem. 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunDigital signature verification is implemented using cut-down kernel port of 23*4882a593SmuzhiyunGnuPG multi-precision integers (MPI) library. The kernel port provides 24*4882a593Smuzhiyunmemory allocation errors handling, has been refactored according to kernel 25*4882a593Smuzhiyuncoding style, and checkpatch.pl reported errors and warnings have been fixed. 26*4882a593Smuzhiyun 27*4882a593SmuzhiyunPublic key and signature consist of header and MPIs:: 28*4882a593Smuzhiyun 29*4882a593Smuzhiyun struct pubkey_hdr { 30*4882a593Smuzhiyun uint8_t version; /* key format version */ 31*4882a593Smuzhiyun time_t timestamp; /* key made, always 0 for now */ 32*4882a593Smuzhiyun uint8_t algo; 33*4882a593Smuzhiyun uint8_t nmpi; 34*4882a593Smuzhiyun char mpi[0]; 35*4882a593Smuzhiyun } __packed; 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun struct signature_hdr { 38*4882a593Smuzhiyun uint8_t version; /* signature format version */ 39*4882a593Smuzhiyun time_t timestamp; /* signature made */ 40*4882a593Smuzhiyun uint8_t algo; 41*4882a593Smuzhiyun uint8_t hash; 42*4882a593Smuzhiyun uint8_t keyid[8]; 43*4882a593Smuzhiyun uint8_t nmpi; 44*4882a593Smuzhiyun char mpi[0]; 45*4882a593Smuzhiyun } __packed; 46*4882a593Smuzhiyun 47*4882a593Smuzhiyunkeyid equals to SHA1[12-19] over the total key content. 48*4882a593SmuzhiyunSignature header is used as an input to generate a signature. 49*4882a593SmuzhiyunSuch approach insures that key or signature header could not be changed. 50*4882a593SmuzhiyunIt protects timestamp from been changed and can be used for rollback 51*4882a593Smuzhiyunprotection. 52*4882a593Smuzhiyun 53*4882a593SmuzhiyunAPI 54*4882a593Smuzhiyun=== 55*4882a593Smuzhiyun 56*4882a593SmuzhiyunAPI currently includes only 1 function:: 57*4882a593Smuzhiyun 58*4882a593Smuzhiyun digsig_verify() - digital signature verification with public key 59*4882a593Smuzhiyun 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun /** 62*4882a593Smuzhiyun * digsig_verify() - digital signature verification with public key 63*4882a593Smuzhiyun * @keyring: keyring to search key in 64*4882a593Smuzhiyun * @sig: digital signature 65*4882a593Smuzhiyun * @sigen: length of the signature 66*4882a593Smuzhiyun * @data: data 67*4882a593Smuzhiyun * @datalen: length of the data 68*4882a593Smuzhiyun * @return: 0 on success, -EINVAL otherwise 69*4882a593Smuzhiyun * 70*4882a593Smuzhiyun * Verifies data integrity against digital signature. 71*4882a593Smuzhiyun * Currently only RSA is supported. 72*4882a593Smuzhiyun * Normally hash of the content is used as a data for this function. 73*4882a593Smuzhiyun * 74*4882a593Smuzhiyun */ 75*4882a593Smuzhiyun int digsig_verify(struct key *keyring, const char *sig, int siglen, 76*4882a593Smuzhiyun const char *data, int datalen); 77*4882a593Smuzhiyun 78*4882a593SmuzhiyunUser-space utilities 79*4882a593Smuzhiyun==================== 80*4882a593Smuzhiyun 81*4882a593SmuzhiyunThe signing and key management utilities evm-utils provide functionality 82*4882a593Smuzhiyunto generate signatures, to load keys into the kernel keyring. 83*4882a593SmuzhiyunKeys can be in PEM or converted to the kernel format. 84*4882a593SmuzhiyunWhen the key is added to the kernel keyring, the keyid defines the name 85*4882a593Smuzhiyunof the key: 5D2B05FC633EE3E8 in the example bellow. 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunHere is example output of the keyctl utility:: 88*4882a593Smuzhiyun 89*4882a593Smuzhiyun $ keyctl show 90*4882a593Smuzhiyun Session Keyring 91*4882a593Smuzhiyun -3 --alswrv 0 0 keyring: _ses 92*4882a593Smuzhiyun 603976250 --alswrv 0 -1 \_ keyring: _uid.0 93*4882a593Smuzhiyun 817777377 --alswrv 0 0 \_ user: kmk 94*4882a593Smuzhiyun 891974900 --alswrv 0 0 \_ encrypted: evm-key 95*4882a593Smuzhiyun 170323636 --alswrv 0 0 \_ keyring: _module 96*4882a593Smuzhiyun 548221616 --alswrv 0 0 \_ keyring: _ima 97*4882a593Smuzhiyun 128198054 --alswrv 0 0 \_ keyring: _evm 98*4882a593Smuzhiyun 99*4882a593Smuzhiyun $ keyctl list 128198054 100*4882a593Smuzhiyun 1 key in keyring: 101*4882a593Smuzhiyun 620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8 102