Back to home page

LXR

 
 

    


0001 Digital Signature Verification API
0002 
0003 CONTENTS
0004 
0005 1. Introduction
0006 2. API
0007 3. User-space utilities
0008 
0009 
0010 1. Introduction
0011 
0012 Digital signature verification API provides a method to verify digital signature.
0013 Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
0014 
0015 Digital signature verification is implemented using cut-down kernel port of
0016 GnuPG multi-precision integers (MPI) library. The kernel port provides
0017 memory allocation errors handling, has been refactored according to kernel
0018 coding style, and checkpatch.pl reported errors and warnings have been fixed.
0019 
0020 Public key and signature consist of header and MPIs.
0021 
0022 struct pubkey_hdr {
0023         uint8_t         version;        /* key format version */
0024         time_t          timestamp;      /* key made, always 0 for now */
0025         uint8_t         algo;
0026         uint8_t         nmpi;
0027         char            mpi[0];
0028 } __packed;
0029 
0030 struct signature_hdr {
0031         uint8_t         version;        /* signature format version */
0032         time_t          timestamp;      /* signature made */
0033         uint8_t         algo;
0034         uint8_t         hash;
0035         uint8_t         keyid[8];
0036         uint8_t         nmpi;
0037         char            mpi[0];
0038 } __packed;
0039 
0040 keyid equals to SHA1[12-19] over the total key content.
0041 Signature header is used as an input to generate a signature.
0042 Such approach insures that key or signature header could not be changed.
0043 It protects timestamp from been changed and can be used for rollback
0044 protection.
0045 
0046 2. API
0047 
0048 API currently includes only 1 function:
0049 
0050         digsig_verify() - digital signature verification with public key
0051 
0052 
0053 /**
0054  * digsig_verify() - digital signature verification with public key
0055  * @keyring:    keyring to search key in
0056  * @sig:        digital signature
0057  * @sigen:      length of the signature
0058  * @data:       data
0059  * @datalen:    length of the data
0060  * @return:     0 on success, -EINVAL otherwise
0061  *
0062  * Verifies data integrity against digital signature.
0063  * Currently only RSA is supported.
0064  * Normally hash of the content is used as a data for this function.
0065  *
0066  */
0067 int digsig_verify(struct key *keyring, const char *sig, int siglen,
0068                                                 const char *data, int datalen);
0069 
0070 3. User-space utilities
0071 
0072 The signing and key management utilities evm-utils provide functionality
0073 to generate signatures, to load keys into the kernel keyring.
0074 Keys can be in PEM or converted to the kernel format.
0075 When the key is added to the kernel keyring, the keyid defines the name
0076 of the key: 5D2B05FC633EE3E8 in the example bellow.
0077 
0078 Here is example output of the keyctl utility.
0079 
0080 $ keyctl show
0081 Session Keyring
0082        -3 --alswrv      0     0  keyring: _ses
0083 603976250 --alswrv      0    -1   \_ keyring: _uid.0
0084 817777377 --alswrv      0     0       \_ user: kmk
0085 891974900 --alswrv      0     0       \_ encrypted: evm-key
0086 170323636 --alswrv      0     0       \_ keyring: _module
0087 548221616 --alswrv      0     0       \_ keyring: _ima
0088 128198054 --alswrv      0     0       \_ keyring: _evm
0089 
0090 $ keyctl list 128198054
0091 1 key in keyring:
0092 620789745: --alswrv     0     0 user: 5D2B05FC633EE3E8
0093 
0094 
0095 Dmitry Kasatkin
0096 06.10.2011