Commit a2fbbcea authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

digsig.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:

- comment the internal index;
- use the proper markups for titles;
- mark literal blocks.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 7effa5b0
==================================
Digital Signature Verification API Digital Signature Verification API
==================================
CONTENTS :Author: Dmitry Kasatkin
:Date: 06.10.2011
1. Introduction
2. API
3. User-space utilities
.. CONTENTS
1. Introduction 1. Introduction
2. API
3. User-space utilities
Introduction
============
Digital signature verification API provides a method to verify digital signature. Digital signature verification API provides a method to verify digital signature.
Currently digital signatures are used by the IMA/EVM integrity protection subsystem. Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
...@@ -17,17 +24,17 @@ GnuPG multi-precision integers (MPI) library. The kernel port provides ...@@ -17,17 +24,17 @@ GnuPG multi-precision integers (MPI) library. The kernel port provides
memory allocation errors handling, has been refactored according to kernel memory allocation errors handling, has been refactored according to kernel
coding style, and checkpatch.pl reported errors and warnings have been fixed. coding style, and checkpatch.pl reported errors and warnings have been fixed.
Public key and signature consist of header and MPIs. Public key and signature consist of header and MPIs::
struct pubkey_hdr { struct pubkey_hdr {
uint8_t version; /* key format version */ uint8_t version; /* key format version */
time_t timestamp; /* key made, always 0 for now */ time_t timestamp; /* key made, always 0 for now */
uint8_t algo; uint8_t algo;
uint8_t nmpi; uint8_t nmpi;
char mpi[0]; char mpi[0];
} __packed; } __packed;
struct signature_hdr { struct signature_hdr {
uint8_t version; /* signature format version */ uint8_t version; /* signature format version */
time_t timestamp; /* signature made */ time_t timestamp; /* signature made */
uint8_t algo; uint8_t algo;
...@@ -35,7 +42,7 @@ struct signature_hdr { ...@@ -35,7 +42,7 @@ struct signature_hdr {
uint8_t keyid[8]; uint8_t keyid[8];
uint8_t nmpi; uint8_t nmpi;
char mpi[0]; char mpi[0];
} __packed; } __packed;
keyid equals to SHA1[12-19] over the total key content. keyid equals to SHA1[12-19] over the total key content.
Signature header is used as an input to generate a signature. Signature header is used as an input to generate a signature.
...@@ -43,14 +50,15 @@ Such approach insures that key or signature header could not be changed. ...@@ -43,14 +50,15 @@ Such approach insures that key or signature header could not be changed.
It protects timestamp from been changed and can be used for rollback It protects timestamp from been changed and can be used for rollback
protection. protection.
2. API API
===
API currently includes only 1 function: API currently includes only 1 function::
digsig_verify() - digital signature verification with public key digsig_verify() - digital signature verification with public key
/** /**
* digsig_verify() - digital signature verification with public key * digsig_verify() - digital signature verification with public key
* @keyring: keyring to search key in * @keyring: keyring to search key in
* @sig: digital signature * @sig: digital signature
...@@ -64,10 +72,11 @@ API currently includes only 1 function: ...@@ -64,10 +72,11 @@ API currently includes only 1 function:
* Normally hash of the content is used as a data for this function. * Normally hash of the content is used as a data for this function.
* *
*/ */
int digsig_verify(struct key *keyring, const char *sig, int siglen, int digsig_verify(struct key *keyring, const char *sig, int siglen,
const char *data, int datalen); const char *data, int datalen);
3. User-space utilities User-space utilities
====================
The signing and key management utilities evm-utils provide functionality The signing and key management utilities evm-utils provide functionality
to generate signatures, to load keys into the kernel keyring. to generate signatures, to load keys into the kernel keyring.
...@@ -75,22 +84,18 @@ Keys can be in PEM or converted to the kernel format. ...@@ -75,22 +84,18 @@ 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 When the key is added to the kernel keyring, the keyid defines the name
of the key: 5D2B05FC633EE3E8 in the example bellow. of the key: 5D2B05FC633EE3E8 in the example bellow.
Here is example output of the keyctl utility. Here is example output of the keyctl utility::
$ keyctl show $ keyctl show
Session Keyring Session Keyring
-3 --alswrv 0 0 keyring: _ses -3 --alswrv 0 0 keyring: _ses
603976250 --alswrv 0 -1 \_ keyring: _uid.0 603976250 --alswrv 0 -1 \_ keyring: _uid.0
817777377 --alswrv 0 0 \_ user: kmk 817777377 --alswrv 0 0 \_ user: kmk
891974900 --alswrv 0 0 \_ encrypted: evm-key 891974900 --alswrv 0 0 \_ encrypted: evm-key
170323636 --alswrv 0 0 \_ keyring: _module 170323636 --alswrv 0 0 \_ keyring: _module
548221616 --alswrv 0 0 \_ keyring: _ima 548221616 --alswrv 0 0 \_ keyring: _ima
128198054 --alswrv 0 0 \_ keyring: _evm 128198054 --alswrv 0 0 \_ keyring: _evm
$ keyctl list 128198054 $ keyctl list 128198054
1 key in keyring: 1 key in keyring:
620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8 620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8
Dmitry Kasatkin
06.10.2011
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment