]>
Commit | Line | Data |
---|---|---|
a2fbbcea | 1 | ================================== |
051dbb91 | 2 | Digital Signature Verification API |
a2fbbcea | 3 | ================================== |
051dbb91 | 4 | |
a2fbbcea MCC |
5 | :Author: Dmitry Kasatkin |
6 | :Date: 06.10.2011 | |
051dbb91 | 7 | |
051dbb91 | 8 | |
a2fbbcea | 9 | .. CONTENTS |
051dbb91 | 10 | |
a2fbbcea MCC |
11 | 1. Introduction |
12 | 2. API | |
13 | 3. User-space utilities | |
14 | ||
15 | ||
16 | Introduction | |
17 | ============ | |
051dbb91 DK |
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 | ||
a2fbbcea MCC |
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; | |
051dbb91 DK |
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 | ||
a2fbbcea MCC |
53 | API |
54 | === | |
051dbb91 | 55 | |
a2fbbcea | 56 | API currently includes only 1 function:: |
051dbb91 DK |
57 | |
58 | digsig_verify() - digital signature verification with public key | |
59 | ||
60 | ||
a2fbbcea MCC |
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 | ==================== | |
051dbb91 DK |
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 | ||
a2fbbcea MCC |
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 |