← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lts-saucy/precise-proposed

« back to all changes in this revision

Viewing changes to Documentation/digsig.txt

  • Committer: Package Import Robot
  • Author(s): Tim Gardner
  • Date: 2013-10-09 13:31:18 UTC
  • Revision ID: package-import@ubuntu.com-20131009133118-l5q5o2hmtz96hefq
Tags: upstream-3.11.0
Import upstream version 3.11.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/digsig.txt
 
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