[GitHub/moto-9609/android_kernel_motorola_exynos9610.git] / Documentation / digsig.txt

==================================
Digital Signature Verification API
==================================

:Author: Dmitry Kasatkin
:Date: 06.10.2011


.. CONTENTS

   1. Introduction
   2. API
   3. User-space utilities


Introduction
============

Digital signature verification API provides a method to verify digital signature.
Currently digital signatures are used by the IMA/EVM integrity protection subsystem.

Digital signature verification is implemented using cut-down kernel port of
GnuPG multi-precision integers (MPI) library. The kernel port provides
memory allocation errors handling, has been refactored according to kernel
coding style, and checkpatch.pl reported errors and warnings have been fixed.

Public key and signature consist of header and MPIs::

	struct pubkey_hdr {
		uint8_t		version;	/* key format version */
		time_t		timestamp;	/* key made, always 0 for now */
		uint8_t		algo;
		uint8_t		nmpi;
		char		mpi[0];
	} __packed;

	struct signature_hdr {
		uint8_t		version;	/* signature format version */
		time_t		timestamp;	/* signature made */
		uint8_t		algo;
		uint8_t		hash;
		uint8_t		keyid[8];
		uint8_t		nmpi;
		char		mpi[0];
	} __packed;

keyid equals to SHA1[12-19] over the total key content.
Signature header is used as an input to generate a signature.
Such approach insures that key or signature header could not be changed.
It protects timestamp from been changed and can be used for rollback
protection.

API
===

API currently includes only 1 function::

	digsig_verify() - digital signature verification with public key


	/**
	* digsig_verify() - digital signature verification with public key
	* @keyring:	keyring to search key in
	* @sig:	digital signature
	* @sigen:	length of the signature
	* @data:	data
	* @datalen:	length of the data
	* @return:	0 on success, -EINVAL otherwise
	*
	* Verifies data integrity against digital signature.
	* Currently only RSA is supported.
	* Normally hash of the content is used as a data for this function.
	*
	*/
	int digsig_verify(struct key *keyring, const char *sig, int siglen,
			  const char *data, int datalen);

User-space utilities
====================

The signing and key management utilities evm-utils provide functionality
to generate signatures, to load keys into the kernel keyring.
Keys can be in PEM or converted to the kernel format.
When the key is added to the kernel keyring, the keyid defines the name
of the key: 5D2B05FC633EE3E8 in the example bellow.

Here is example output of the keyctl utility::

	$ keyctl show
	Session Keyring
	-3 --alswrv      0     0  keyring: _ses
	603976250 --alswrv      0    -1   \_ keyring: _uid.0
	817777377 --alswrv      0     0       \_ user: kmk
	891974900 --alswrv      0     0       \_ encrypted: evm-key
	170323636 --alswrv      0     0       \_ keyring: _module
	548221616 --alswrv      0     0       \_ keyring: _ima
	128198054 --alswrv      0     0       \_ keyring: _evm

	$ keyctl list 128198054
	1 key in keyring:
	620789745: --alswrv     0     0 user: 5D2B05FC633EE3E8
Commit	Line	Data
a2fbbcea	1	==================================
051dbb91	2	Digital Signature Verification API
a2fbbcea	3	==================================
051dbb91	4
a2fbbcea MCC	5	:Author: Dmitry Kasatkin
a2fbbcea MCC	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
a2fbbcea MCC	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