About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / digsig.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:02 EST.

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
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.