Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753301AbdFQPnv (ORCPT ); Sat, 17 Jun 2017 11:43:51 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:38498 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752668AbdFQP0B (ORCPT ); Sat, 17 Jun 2017 11:26:01 -0400 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH v2 12/31] digsig.txt: standardize document format Date: Sat, 17 Jun 2017 12:25:31 -0300 Message-Id: <0a985c925e6a9e48b6acca48fcf61eecf7081f52.1497713142.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.9.4 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 5559 Lines: 181 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: Mauro Carvalho Chehab --- Documentation/digsig.txt | 125 ++++++++++++++++++++++++----------------------- 1 file changed, 65 insertions(+), 60 deletions(-) diff --git a/Documentation/digsig.txt b/Documentation/digsig.txt index 3f682889068b..f6a8902d3ef7 100644 --- a/Documentation/digsig.txt +++ b/Documentation/digsig.txt @@ -1,13 +1,20 @@ +================================== 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. Currently digital signatures are used by the IMA/EVM integrity protection subsystem. @@ -17,25 +24,25 @@ 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. +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 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; + 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. @@ -43,31 +50,33 @@ 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. -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 - * @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); + /** + * 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); -3. User-space utilities +User-space utilities +==================== The signing and key management utilities evm-utils provide functionality 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. 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 - - -Dmitry Kasatkin -06.10.2011 +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 -- 2.9.4