/mandos/release

To get this branch, use:
bzr branch http://bzr.recompile.se/loggerhead/mandos/release

« back to all changes in this revision

Viewing changes to mandos-ctl.xml

  • Committer: Teddy Hogeborn
  • Date: 2021-03-21 20:46:40 UTC
  • mto: This revision was merged to the branch mainline in revision 406.
  • Revision ID: teddy@recompile.se-20210321204640-lpsyen8jr9lw1jma
Some cleanup of GnuTLS interface

Rename opaque internal GnuTLS structures named *_int to also start
with underscore (_), as is the custom in Python programs.

Decode byte strings from UTF-8 where needed.  (Fixing, among other
things, all "DEBUG: GnuTLS" lines having a "b'" prefix in Python 3.)

Simplify calling C functions by:
1. Using the "_as_parameter_" attribute to store the ctypes object.
2. Creating and using helper classes to automatically create pointers
   or cast typed pointers to pointers to void.
3. Providing the "from_param()" method on relevant classes.

Remove "restype" attribute on C functions where "errcheck" attribute
is already set.

* mandos (gnutls.session_int): Rename to start with "_".
  (gnutls.openpgp_crt_int): - '' -
  (gnutls.Error.__init__): Decode byte string from gnutls.strerror().
  (gnutls.PointerTo): New helper class.
  (gnutls.CastToVoidPointer): - '' -
  (gnutls.With_from_param): - '' -
  (gnutls.Credentials): Inherit from "With_from_param" and store the
  ctypes object in the "_as_parameter_" attribute instead of
  "_c_object".
  (gnutls._error_code): Use "gnutls.E_SUCCESS" instead of the unadorned
  numerical constant "0".
  (gnutls._retry_on_error): - '' -
  (gnutls.priority_set_direct.argtypes): Use "ClientSession" instead
  of "session_t", and change all callers to match.
  (gnutls.init.argtypes): Use "PointerTo(ClientSession)" instead of
  "ctypes.POINTER(session_t)", and change all callers to match.
  (gnutls.set_default_priority.argtypes): Use "ClientSession" instead
  of "session_t", and change all callers to match.
  (gnutls.record_send.argtypes): - '' -
  (gnutls.certificate_allocate_credentials.argtypes): Use
  "PointerTo(Credentials)" instead of
  "ctypes.POINTER(certificate_credentials_t)", and change all callers
  to match.
  (gnutls.certificate_free_credentials.argtypes): Use "Credentials"
  instead of "certificate_credentials_t", and change all callers to
  match.
  (gnutls.handshake_set_private_extensions.argtypes): Use
  "ClientSession" instead of "session_t", and change all callers to
  match.
  (gnutls.credentials_set.argtypes): Use
  "CastToVoidPointer(Credentials)" instead of "ctypes.c_void_p", and
  change all callers to match.
  (gnutls.certificate_type_get.argtypes): Use "ClientSession" instead
  of "session_t", and change all callers to match.
  (gnutls.certificate_get_peers.argtypes): - '' -
  (gnutls.deinit.argtypes): - '' -
  (gnutls.handshake.argtypes): - '' -
  (gnutls.handshake.restype): Change from "_error_code" to
  "ctypes.c_int".
  (gnutls.transport_set_ptr.argtypes): Use "ClientSession" instead of
  "session_t", and change all callers to match.
  (gnutls.bye.argtypes): - '' -
  (gnutls.bye.restype): Change from "_error_code" to "ctypes.c_int".
  (gnutls.certificate_type_get2.argtypes): Use "ClientSession" instead
  of "session_t", and change all callers to match.
  (ClientHandler.handle): Decode "key_id" bytes to string before
  logging it in the debug log.
  (main.debug_gnutls): Decode GnuTLS log message from bytes to string
  before logging it in the debug log.

Show diffs side-by-side

added added

removed removed

Lines of Context:
2
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3
3
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4
4
<!ENTITY COMMANDNAME "mandos-ctl">
5
 
<!ENTITY TIMESTAMP "2016-06-27">
 
5
<!ENTITY TIMESTAMP "2019-07-29">
6
6
<!ENTITY % common SYSTEM "common.ent">
7
7
%common;
8
8
]>
38
38
      <year>2014</year>
39
39
      <year>2015</year>
40
40
      <year>2016</year>
 
41
      <year>2017</year>
 
42
      <year>2018</year>
 
43
      <year>2019</year>
41
44
      <holder>Teddy Hogeborn</holder>
42
45
      <holder>Björn Påhlsson</holder>
43
46
    </copyright>
59
62
  <refsynopsisdiv>
60
63
    <cmdsynopsis>
61
64
      <command>&COMMANDNAME;</command>
 
65
      <group>
 
66
          <arg choice="plain"><option>--verbose</option></arg>
 
67
          <arg choice="plain"><option>-v</option></arg>
 
68
          <sbr/>
 
69
          <arg choice="plain"><option>--dump-json</option></arg>
 
70
          <arg choice="plain"><option>-j</option></arg>
 
71
      </group>
 
72
      <arg><option>--debug</option></arg>
 
73
      <group>
 
74
        <arg rep='repeat' choice='plain'>
 
75
          <replaceable>CLIENT</replaceable>
 
76
        </arg>
 
77
      </group>
 
78
    </cmdsynopsis>
 
79
    <cmdsynopsis>
 
80
      <command>&COMMANDNAME;</command>
62
81
      <group choice="req">
63
82
        <group>
64
83
          <arg choice="plain"><option>--enable</option></arg>
75
94
        <sbr/>
76
95
        <group>
77
96
          <arg choice="plain"><option>--start-checker</option></arg>
78
 
        </group>
79
 
        <sbr/>
80
 
        <group>
81
97
          <arg choice="plain"><option>--stop-checker</option></arg>
82
98
        </group>
83
99
        <sbr/>
84
100
        <group>
85
 
          <arg choice="plain"><option>--remove</option></arg>
86
 
          <arg choice="plain"><option>-r</option></arg>
87
 
        </group>
88
 
        <sbr/>
89
 
        <group>
90
101
          <arg choice="plain"><option>--checker
91
102
          <replaceable>COMMAND</replaceable></option></arg>
92
103
          <arg choice="plain"><option>-c
130
141
        </group>
131
142
        <sbr/>
132
143
        <group>
133
 
          <arg choice="plain"><option>--interval
134
 
          <replaceable>TIME</replaceable></option></arg>
135
 
          <arg choice="plain"><option>-i
136
 
          <replaceable>TIME</replaceable></option></arg>
137
 
        </group>
138
 
        <sbr/>
139
 
        <group>
140
144
          <arg choice="plain"><option>--host
141
145
          <replaceable>STRING</replaceable></option></arg>
142
146
          <arg choice="plain"><option>-H
159
163
        </group>
160
164
      </group>
161
165
      <sbr/>
 
166
      <arg><option>--debug</option></arg>
162
167
      <group choice="req">
163
168
        <arg choice="plain"><option>--all</option></arg>
164
169
        <arg choice="plain"><option>-a</option></arg>
170
175
    <cmdsynopsis>
171
176
      <command>&COMMANDNAME;</command>
172
177
      <group>
173
 
          <arg choice="plain"><option>--verbose</option></arg>
174
 
          <arg choice="plain"><option>-v</option></arg>
175
 
          <sbr/>
176
 
          <arg choice="plain"><option>--dump-json</option></arg>
177
 
          <arg choice="plain"><option>-j</option></arg>
178
 
      </group>
179
 
      <group>
 
178
        <arg choice="plain"><option>--deny</option></arg>
 
179
        <arg choice="plain"><option>-D</option></arg>
 
180
      </group>
 
181
      <group choice="req">
 
182
          <arg choice="plain"><option>--remove</option></arg>
 
183
          <arg choice="plain"><option>-r</option></arg>
 
184
      </group>
 
185
      <sbr/>
 
186
      <arg><option>--debug</option></arg>
 
187
      <group choice="req">
 
188
        <arg choice="plain"><option>--all</option></arg>
 
189
        <arg choice="plain"><option>-a</option></arg>
180
190
        <arg rep='repeat' choice='plain'>
181
191
          <replaceable>CLIENT</replaceable>
182
192
        </arg>
188
198
        <arg choice="plain"><option>--is-enabled</option></arg>
189
199
        <arg choice="plain"><option>-V</option></arg>
190
200
      </group>
 
201
      <arg><option>--debug</option></arg>
191
202
      <arg choice='plain'><replaceable>CLIENT</replaceable></arg>
192
203
    </cmdsynopsis>
193
204
    <cmdsynopsis>
501
512
      </varlistentry>
502
513
      
503
514
      <varlistentry>
 
515
        <term><option>--debug</option></term>
 
516
        <listitem>
 
517
          <para>
 
518
            Show debug output; currently, this means show D-Bus calls.
 
519
          </para>
 
520
        </listitem>
 
521
      </varlistentry>
 
522
      
 
523
      <varlistentry>
504
524
        <term><option>--check</option></term>
505
525
        <listitem>
506
526
          <para>
537
557
  
538
558
  <refsect1 id="example">
539
559
    <title>EXAMPLE</title>
 
560
    <!-- Name of test methods in class Test_commands_from_options are
 
561
         written in comments below.  When adding an example, add a
 
562
         test too which tests the documented behavior. -->
540
563
    <informalexample>
 
564
      <!-- Test method: test_manual_page_example_1() -->
541
565
      <para>
542
566
        To list all clients:
543
567
      </para>
547
571
    </informalexample>
548
572
    
549
573
    <informalexample>
 
574
      <!-- Test method: test_manual_page_example_2() -->
550
575
      <para>
551
576
        To list <emphasis>all</emphasis> settings for the clients
552
577
        named <quote>foo1.example.org</quote> and <quote
561
586
    </informalexample>
562
587
    
563
588
    <informalexample>
 
589
      <!-- Test method: test_manual_page_example_3() -->
564
590
      <para>
565
591
        To enable all clients:
566
592
      </para>
570
596
    </informalexample>
571
597
    
572
598
    <informalexample>
 
599
      <!-- Test method: test_manual_page_example_4() -->
573
600
      <para>
574
601
        To change timeout and interval value for the clients
575
602
        named <quote>foo1.example.org</quote> and <quote
578
605
      <para>
579
606
 
580
607
<!-- do not wrap this line -->
581
 
<userinput>&COMMANDNAME; --timeout="5m" --interval="1m" foo1.example.org foo2.example.org</userinput>
 
608
<userinput>&COMMANDNAME; --timeout=PT5M --interval=PT1M foo1.example.org foo2.example.org</userinput>
582
609
 
583
610
      </para>
584
611
    </informalexample>
585
612
    
586
613
    <informalexample>
 
614
      <!-- Test method: test_manual_page_example_5() -->
587
615
      <para>
588
 
        To approve all clients currently waiting for it:
 
616
        To approve all clients currently waiting for approval:
589
617
      </para>
590
618
      <para>
591
619
        <userinput>&COMMANDNAME; --approve --all</userinput>