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