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