GNU Linux-libre 4.19.264-gnu1
[releases.git] / Documentation / digsig.txt
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