man page for AuditVerify https://fedorahosted.org/pki/ticket/2246
thanks, Christina
>From 79aba2c8b2d507649a1d65e429f3cf42b3740471 Mon Sep 17 00:00:00 2001 From: Christina Fu <[email protected]> Date: Tue, 12 Jul 2016 18:18:39 -0700 Subject: [PATCH] Ticket #2246 [MAN] Man Page: AuditVerify This patch contains the man page for AuditVerify. --- base/java-tools/man/man1/AuditVerify.1 | 113 +++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 base/java-tools/man/man1/AuditVerify.1 diff --git a/base/java-tools/man/man1/AuditVerify.1 b/base/java-tools/man/man1/AuditVerify.1 new file mode 100644 index 0000000000000000000000000000000000000000..252e41ef5304fc7eaf06e8084067e4b33df9fff1 --- /dev/null +++ b/base/java-tools/man/man1/AuditVerify.1 @@ -0,0 +1,113 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH AuditVerify 1 "July 7, 2016" "version 10.3" "PKI Signed Audit Log Verification Command" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +AuditVerify \- Command-Line utility for verifying Certificate System signed audit logs. + +.SH SYNOPSIS +.nf +\fBAuditVerify\fR -d <dbdir> -n <signing_certificate_nickname> -a <logListFile> [-P cert/key_db_prefix] [-v] +.fi + +.SH DESCRIPTION +.PP +The \fBAuditVerify\fR command provides command-line utility to verify that signed audit logs were signed with the appropriate CS audit private signing key and that the audit logs have not been compromised. Auditors can verify the authenticity and integrity of signed audit logs using the \fBAuditVerify\fR tool. This tool uses the public key of the signed audit log signing certificate to verify the digital signatures embedded in a signed audit log file. The tool result indicates either that the signed audit log was successfully verified or that the signed audit log was not successfully verified. An unsuccessful verification warns the auditor that the signature failed to verify, indicating the log file may have been tampered with (compromised). +.PP + +.SH OPTIONS +.TP +.B -d <dbdir> +Specifies the directory containing the security databases with the imported audit log signing certificate. This directory is almost always the auditor's own personal certificate databases in a personal directory, such as ~jsmith/auditVerifyDir/. + +.TP +.B -n <signing_certificate_nickname> +Gives the nickname of the certificate used to sign the log files. The nickname is whatever was used when the log signing certificate was imported into that database. + +.TP +.B [-P cert/key_db_prefix] +Optional. The prefix to prepend to the certificate and key database filenames. If used, a value of empty quotation marks (ââ) should be specified for this argument, since the auditor is using separate certificate and key databases from the Certificate System instance and it is unlikely that the prefix should be prepended to the new audit security database files. + +.TP +.B -a <logListFile> +Specifies the file which contains the comma-separate list of file paths(in chronological order) of the signed audit logs to be verified. +This file should be created in a directory which is writeable by the auditor, such as a special auditing directory like ~jsmith/auditDir. +The contents of the logListFile are the full paths to the audit logs. For example: +.PP +.nf + /var/log/pki/pki-ca/ca/signedAudit/ca_audit,/var/log/pki/pki-ca/ca/signedAudit/ca_audit.20030227102711,/var/log/pki/pki-ca/ca/signedAudit/ca_audit.20030226094015 +.fi + +.TP +.B [-v] +Optional. Specifies verbose output. + +.SH Setting up the Auditor's Database + +\fBAuditVerify\fP needs access to a set of security databases (usually the auditor's personal security databases) containing the signed audit log signing certificate and its chain of issuing certificates. One of the CA certificates in the issuance chain must be marked as trusted in the database. +.PP +Auditors should import the audit signing certificate into their personal certificate database before running \fBAuditVerify\fP. The auditor should not use the security databases of the Certificate System instance that generated the signed audit log files. If there are no readily accessible certificate and key database, the auditor must create a set of certificate and key databases and import the signed audit log signing certificate chain. +.PP +To create the security databases and import the certificate chain: + +.SS Create a special directory in the auditor's home directory to use to perform the verification. For example: + +mkdir ~jsmith/auditVerifyDir + +.SS Use the certutil tool to create an empty set of certificate databases in the auditor's home directory. + +certutil -d ~jsmith/auditVerifyDir -N + +.SS Download the CA certificate from the CA's Retrieval page. The certificates can be obtained from the CA in ASCII format. + +https://server.example.com:ca_https_port/ca/ee/ca/ + +.SS Import the CA certificate and log signing certificate into the databases and set trust of the certificates + +If the CA certificate is in a file called cacert.txt and the log signing certificate is in a file called logsigncert.txt, then the certutil can be used to set the trust for the new audit security database directory pointing to those files, as follows: + +certutil -d ~jsmith/auditVerifyDir/ -A -n "CA Certificate" -t "CT,CT,CT" -a -i /var/lib/instance_ID/alias/cacert.txt + +certutil -d ~jsmith/auditVerifyDir -A -n "Log Signing Certificate"-t ",,P" -a -i /var/lib/instance_ID/alias/logsigncert.txt + +.B Note: The signedAudit directory kept by the subsystem is not writeable by any user, including auditors. + +.B Note: The auditor user must be a member of one of the following: + +the pkiaudit group, which is the default value of the pki_audit_group variable under the [DEFAULT] section of the /etc/pki/default.cfg file + +whatever system group was identified as the audit group by overriding the pki_audit_group variable when the pkispawn utility was run to create the subsystem + +.SH Operation +After a separate audit database directory has been configured, do the following: +.SS Create a text file containing a comma-separated list of the log files to be verified. The name of this file is referenced in the AuditVerify command. + +For example, this file could be logListFile in the /etc/audit directory. The contents are the comma-separated list of audit logs to be verified, such as "auditlog.1213, auditlog.1214, auditlog.1215." + +.SS If the audit databases do not contain prefixes and are located in the user home directory, such as /home/smith/.mozilla, and the signing certificate nickname is "auditsigningcert", the AuditVerify command is run as follows: + +AuditVerify -d ~jsmith/auitVerifyDir -n auditsigningcert -a /etc/audit/logListFile -P "" -v + + +.SH AUTHORS +Christina Fu <[email protected]>. + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public +License, version 2 (GPLv2). A copy of this license is available at +http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki(1) -- 2.7.4
_______________________________________________ Pki-devel mailing list [email protected] https://www.redhat.com/mailman/listinfo/pki-devel
