From 88b639d7dc90580bcc49ba28bc7e03c3db766ed6 Mon Sep 17 00:00:00 2001 From: Willem Toorop Date: Tue, 18 Sep 2012 08:31:26 +0000 Subject: [PATCH] Shorter usage help and manpage for verbose usage description --- examples/ldns-dane.1 | 164 +++++++++++++++++++++++++++++++++++++++++++ examples/ldns-dane.c | 96 ++++++++----------------- 2 files changed, 194 insertions(+), 66 deletions(-) create mode 100644 examples/ldns-dane.1 diff --git a/examples/ldns-dane.1 b/examples/ldns-dane.1 new file mode 100644 index 00000000..aac16252 --- /dev/null +++ b/examples/ldns-dane.1 @@ -0,0 +1,164 @@ +.TH ldns-dane 1 "17 September 2012" +.SH NAME +ldns-dane \- verify or create TLS authentication with DANE (RFC6698) +.SH SYNOPSIS +.PD 0 +.B ldns-dane +.IR [OPTIONS] +.IR name +.IR port +.PP +.B ldns-dane +.IR [OPTIONS] +.IR -t +.IR tlsafile + +.B ldns-dane +.IR [OPTIONS] +.IR name +.IR port +.IR Certificate-usage +.IR Selector +.IR Matching-type + +.B ldns-dane +.IR -h +.PP +.B ldns-dane +.IR -v +.PD 1 + +.SH DESCRIPTION + +In the first two forms ldns-dane will be in \fBverify\fR modus. +In the third form in \fBcreate\fR modus. + +In the first form: +A TLS connection to \fIname\fR:\fIport\fR is made. The TLSA resource +record(s) for \fIname\fR are used to authenticate the connection. + +In the second form: +The TLSA record(s) are read from \fItlsafile\fR and user to authenticate +the TLS service they reference. + +In the third form: +A TLS connection to \fIname\fR:\fIport\fR is made and used to create the TLSA +resource record(s) that would authenticate the connection. +The parameters that determine the form of the TLSA records to be created +are: + +.PD 0 +.I Certificate-usage\fR: +.RS +.IP 0 +CA constraint +.IP 1 +Service certificate constraint +.IP 2 +Trust anchor assertion +.IP 3 +Domain-issued certificate +.RE + +.I Selector\fR: +.RS +.IP 0 +Full certificate +.IP 1 +SubjectPublicKeyInfo +.RE + +.I Matching-type\fR: +.RS +.IP 0 +No hash used +.IP 1 +SHA-256 +.IP 2 +SHA-512 +.RE +.PD 1 + +In case of numbers the first few letters of the intended meaning may be used. +Except for the hash algorithm names in which need the full name. + +.SH OPTIONS +.IP -4 +TLS connect IPv4 only +.IP -6 +TLS connect IPv6 only +.IP "-a \fIaddress\fR" +Don't try to resolve \fIname\fR, but connect to \fIaddress\fR in stead. + +This option may be given more than once. +.IP -b +print "\fIname\fR\. TYPE52 \\#\fIsize\fR \fIhexdata\fR" form in stead +of TLSA presentation format. +.IP "-c \fIcertfile\fR" +Do not TLS connect to \fIname\fR:\fIport\fR, but authenticate (or make +TLSA records) for the certificate (chain) in \fIcertfile\fR in stead. +.IP -d +Assume DNSSEC validity even when the TLSA records were acquired insecure +or were bogus. +.IP "-f \fICAfile\fR" +Use CAfile to validate. +.IP -h +Print short usage help +.IP -i +Interact after connecting. +.IP "-k \fIkeyfile\fR" +Specify a file that contains a trusted DNSKEY or DS rr. +Without a trusted DNSKEY, the local network is trusted to provide +a DNSSEC resolver (i.e. AD bit is checked). + +When \fB-r\fR \fIhintsfile\fR is also given, DNSSEC validation is "traced" +from the root down. With only \fB-k\fR \fIkeyfile\fR and no root hints, +signature(s) are chased to a known key. + +This option may be given more than once. +.IP -n +Do \fBnot\fR verify server name in certificate. +.IP "-o \fIoffset\fR" +When creating a "Trust anchor assertion" TLSA resource record, +select the \fIoffset\fRth certificate offset from the end +of the validation chain. 0 means the last certificate, 1 the one but last, +2 the second but last, etc. + +When \fIoffset\fR is -1 (the default), the last certificate +is used (like with 0) that MUST be self-signed. This can help to make +sure that the intended (self signed) trust anchor is actually present +in the server certificate chain (which is a DANE requirement). +.IP "-p \fICApath\fR" +Use certificates in the \fICApath\fR directory to validate. +.IP "-r \fIhintsfile\fR" +Use \fIhintsfile\fR to read root hints from. +.IP -s +When creating TLSA resource records with the "CA Constraint" and the +"Service Certificate Constraint" certificate usage, do not validate and +assume PKIX is valid. + +For "CA Constraint" this means that verification should end with a +self-signed certificate. +.IP "-t \fItlsafile\fR" +Read TLSA record(s) from \fItlsafile\fR. When \fIname\fR and \fIport\fR +are also given, only TLSA records that match the \fIname\fR, \fIport\fR and +\fItransport\fR are used. Otherwise the owner name of the TLSA record(s) +will be used to determine \fIname\fR, \fIport\fR and \fItransport\fR. +.IP -u +Use UDP transport in stead of TCP to TLS connect. +.IP -v +Show version and exit. +.IP "-V \fI[0-5]\fR +Set verbosity level (defaul 3) + +.SH AUTHOR +Written by the ldns team as an example for ldns usage. + +.SH REPORTING BUGS +Report bugs to \fIldns-team@nlnetlabs.nl\fR. + +.SH COPYRIGHT +Copyright (C) 2012 NLnet Labs. This is free software. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR +PURPOSE. + diff --git a/examples/ldns-dane.c b/examples/ldns-dane.c index 40989db6..482a3ee6 100644 --- a/examples/ldns-dane.c +++ b/examples/ldns-dane.c @@ -41,17 +41,14 @@ void print_usage(const char* progname) { printf("Usage: %s [OPTIONS] \n", progname); - printf("\n\tMake a TLS connection to " - "and use the TLSA\n\t" - "resource record(s) at to authenticate " - "the connection.\n"); - printf("\n or: %s [OPTIONS] -t \n", progname); - printf("\n\tRead TLSA record(s) from and authenticate the\n" + printf(" or: %s [OPTIONS] -t \n", progname); + printf("\n\tVerify the TLS connection at : or" + "\n\tuse TLSA record(s) from to verify the\n" "\tTLS service they reference.\n"); - printf("\n or: %s [OPTIONS] " - "\n", progname); - printf("\n\tMake a TLS connection to " - "and create the TLSA\n\t" + printf("\n or: %s [OPTIONS] " + "\n", progname); + printf("\n\tUse the TLS connection(s) to " + "to create the TLSA\n\t" "resource record(s) that would " "authenticate the connection.\n"); printf("\n\t" @@ -62,77 +59,44 @@ print_usage(const char* progname) printf("\n\t" "\t0: Full certificate\n" "\t\t\t1: SubjectPublicKeyInfo\n"); - printf("\n\t" + printf("\n\t" "\t0: No hash used\n" "\t\t\t1: SHA-256\n" "\t\t\t2: SHA-512\n"); - printf("\nOPTIONS:\n"); - printf("\t-h\t\tshow this text\n\n"); + printf("OPTIONS:\n"); + printf("\t-h\t\tshow this text\n"); printf("\t-4\t\tTLS connect IPv4 only\n"); - printf("\t-6\t\tTLS connect IPv6 only\n\n"); + printf("\t-6\t\tTLS connect IPv6 only\n"); printf("\t-a
\t" - "Don't try to resolve , but connect to
\n" - "\t\t\tin stead.\n" - "\t\t\tThis option may be given more than once.\n" - "\n" - ); + "don't resolve , but connect to
(es)\n"); printf("\t-b\t\t" "print \". TYPE52 \\# \" form\n" - "\t\t\tin stead of TLSA presentation format.\n" - "\n" ); - printf("\t-c \t" - "do not TLS connect to ,\n" - "\t\t\tbut authenticate (or make TLSA records)\n" - "\t\t\tfor the certificate (chain) in in stead\n" - "\n" + printf("\t-c \t" + "verify or create TLSA records for the\n" + "\t\t\tcertificate (chain) in \n" ); - printf("\t-d\t\tassume DNSSEC validity even when insecure\n\n"); - printf("\t-f \tuse CAfile to validate\n\n"); - printf("\t-i\t\tinteract after connecting\n\n"); - printf("\t-k \t" - "specify a file that contains a trusted DNSKEY or DS rr.\n" - "\t\t\tWithout a trusted DNSKEY, the local network is trusted\n" - "\t\t\tto provide a DNSSEC resolver (i.e. AD bit is checked).\n" - "\n" - "\t\t\tWhen -r is also given, DNSSEC validation is\n" - "\t\t\t\"traced\" from the root down. With only -k and\n" - "\t\t\tno root hints, signature(s) are chased to a known key.\n" - "\n" - "\t\t\tThis option may be given more than once.\n" - "\n" + printf("\t-d\t\tassume DNSSEC validity even when insecure\n"); + printf("\t-f \tuse CAfile to validate\n"); + printf("\t-i\t\tinteract after connecting\n"); + printf("\t-k \t" + "use DNSKEY/DS rr(s) in to validate TLSAs\n" ); - printf("\t-n\t\tDo *not* verify server name in certificate\n\n"); - printf("\t-o \t" - "When creating a \"Trust anchor assertion\" TLSA resource\n" - "\t\t\trecord, select the th certificate offset from\n" - "\t\t\tthe end of the validation chain. 0 means the last\n" - "\t\t\tcertificate, 1 the one but last, 2 the second but\n" - "\t\t\tlast, etc.\n" - "\n" - "\t\t\tWhen is -1 (the default), the last certificate" - "\n\t\t\tis used (like with 0) that MUST be self-signed. This\n" - "\t\t\tcan help to make sure that the intended (self signed)\n" - "\t\t\ttrust anchor is actually present in the server certi-\n" - "\t\t\tficate chain (which is a DANE requirement)\n" - "\n" + printf("\t-n\t\tdo *not* verify server name in certificate\n"); + printf("\t-o \t" + "select th certificate from the end of\n" + "\t\t\tthe validation chain. -1 means self-signed at end\n" ); printf("\t-p \t" "use certificates in the directory to validate\n" - "\n" ); - printf("\t-r \tuse to read root hints from\n\n"); - printf("\t-s\t\twhen creating TLSA resource records with the\n\t\t\t" - "\"CA Constraint\" and the \"Service Certificate\n\t\t\t" - "Constraint\" certificate usage, do not validate and\n\t\t\t" - "assume PKIX is valid.\n\n\t\t\t" - "For \"CA Constraint\" this means that verification\n\t\t\t" - "should end with a self-signed certificate.\n\n"); - printf("\t-t \tRead TLSA record(s) from \n\n"); - printf("\t-u\t\tuse UDP in stead of TCP to TLS connect\n\n"); - printf("\t-v\t\tshow version and exit\n\n"); - printf("\t-V [0-5]\tSet verbosity level (defaul 3)\n\n"); + printf("\t-r \tuse to read root hints from\n"); + printf("\t-s\t\tassume PKIX validity\n"); + printf("\t-t \tread TLSA record(s) from \n"); + printf("\t-u\t\tuse UDP in stead of TCP to TLS connect\n"); + printf("\t-v\t\tshow version and exit\n"); + printf("\t-V [0-5]\tset verbosity level (defaul 3)\n"); exit(EXIT_SUCCESS); } -- 2.47.3