10.0.0.21 Git - midget/blob - README.md

   1 # Midget: Commandline interface to IMAP documents
   2
   3 > *The midget and midput commandline utilities let you download and
   4 > upload email attachments from/to your IMAP mailbox, almost as if you
   5 > are using SCP or a similar cross-platform copying command.*
   6
   7 You know about the shepherd boy who slayed a giant with his sling shot?
   8 Keep reading...
   9
  10 ## What is this?
  11
  12 Midget solves a problem that is so common that you might not have
  13 noticed it. But it can really aid the automation of our daily tasks.
  14
  15 You probably recognise this workflow:
  16
  17 1.  You receive a document or package over email
  18
  19 2.  You save the attachment
  20
  21 3.  You move it to another system
  22
  23 4.  On that system, you process it further (unpackaging, saving,
  24     printing, …)
  25
  26 This flow can be greatly simplified. On the shell of the target machine,
  27 you can simply run:
  28
  29     midget mid:opq cid:stu mid:uvw/xyz...
  30
  31 This will retrieve documents with `mid:` or `cid:` URIs from your IMAP
  32 account. These URIs are used to mark documents with a MIME-Type, and are
  33 defined as pragmatically unique identities generated on the sending
  34 site. They may occur in multiple places, but since these ought to be the
  35 same only one will be retrieved by midget. MIME markings such as
  36 filename proposals are taken into account; transport encoding is undone
  37 but content encoding is not.
  38
  39 There is a counterpart to this command:
  40
  41     midput file1 file2 file3
  42
  43 This will construct a new draft email in your IMAP account. The new
  44 draft will have the given files as attachments. You can access the draft
  45 in your graphical browser to enter what gave you the idea to send these
  46 files.
  47
  48 ## What is required to make this work?
  49
  50 These commands rely on Kerberos Single SignOn. Meaning, you are in a
  51 shell account that shows a non-expired principal ticket when you run:
  52
  53     klist
  54
  55 If not, logon to your REALM first, using:
  56
  57     kinit
  58
  59 Your principal name is of the form `user@REALM` and midget and midput
  60 interpret the REALM part as a DNS domain name. Under this domain name,
  61 it will look for a `_kerberos` TXT record to confirm the case-sensitive
  62 REALM value. Note that letters in this record are translated to
  63 uppercase, unless they are escaped with a single '=' character prefix.
  64
  65 There is some upheaval about the reliability of DNS for this sort of
  66 lookup; midget and midput will mostly be used on locally hosted domains,
  67 and if not then it is nowadays a good practice to use DNSSEC to overcome
  68 such problems.
  69
  70 Given DNS confirmation, the derived domain name is queried for an IMAP
  71 server as declared in SRV records. This server is then approached,
  72 Kerberos-based authentication is performed. During authentication, a
  73 login name is sent to the IMAP server. For `user/detail@REALM` names,
  74 this will be detail; for `user@REALM` names, this will be user. For any
  75 other forms (if they exist at all), this will be the local account name
  76 under which you are logged in.
  77
  78 **TODO:** For now, you need to manually configure the IMAP server name
  79 in the midget and midput scripts. They are set in the variable
  80 remote\_hostname.
  81
  82 ## Where do the filenames come from?
  83
  84 Each of the retrieved files is stored in the filesystem. The tool will
  85 create a file named after the `Message-` or `Content-ID`; if it already
  86 exists it will fail and complain; you probably downloaded the same
  87 content twice, and if not then this may be a sign that the sender is
  88 trying to overwrite local files on your system, which is a warning sign.
  89 If a filename is found in the descriptive information sent along the
  90 attachmant, then midget will try to create a link with that filename as
  91 well; this will fail with a non-fatal warning if the filename exists.
  92
  93 Note that the unique value of the `Message-` or `Content-ID` is the
  94 reason to not be cautious when writing a file by that name. It would be
  95 incredibly unlikely that you had a file on your system with the same
  96 name. And yes, some thought is necessary to avoid local files
  97 overwritten by submitted devious content. So perhaps it is better to
  98 raise a fatal error if the name already exists?
  99
 100 ## Desktop tool support
 101
 102 Mailers may hide the `mid:` and `cid:` URIs from you, the silly mouse
 103 operator. It would be advised to use these URIs as copy/paste format, as
 104 well as what gets pasted into a shell when an attechment is dragged into
 105 it.
 106
 107 Maybe this will be a battle, maybe not. As so often, the commandline is
 108 leading the way forward, and welcoming the GUI to follow suit ;-)
 109
 110 It is certainly useful to be able to use `mid:` and `cid:` references in
 111 chat sessions, to refer back to a previously exchanged email attachment.
 112
 113 ## Generating these URIs
 114
 115 If you are building a tool that handles email messages, you should
 116 consider offering a clickable `mid:` URI to access the message body and
 117 any attachments.
 118
 119 Operating systems and browsers generally support new URI schemes with a
 120 registry, and applications can be setup to register against those. It is
 121 easily imaginable that desktop versions of midget are created to handle
 122 such downloads.
 123
 124 Another advantage of visible `mid:` URIs is that they can be copy/pasted
 125 or dragged into shells, chat sessions, and so on. This makes them usable
 126 to crossover to remote locations, where the files can then be used. You
 127 may not want to offer this is the only option, but it certainly is a
 128 useful option to offer to end users.
 129
 130 You should not generate `cid:` URIs if you can avoid it. The `mid:`
 131 format includes the `Message-ID`, and that is a bit more work but it
 132 saves a lot of search time when downloading it. This is due to the IMAP
 133 protocol, which has special constructs for matches with header names
 134 such as the `Message-ID`, but not for MIME-headers such as `Content-ID`.
 135 The latter must therefore be resolved with full-text search, and that is
 136 not open to optimisations like the `Message-ID` is.
 137
 138 Read [RFC 2392][] for details; but in short, you will be removing
 139 angular brackets and applying percent-escaping to the remainder. Be sure
 140 to also escape any slash that occurs in the string. If you are setting
 141 up a `mid:` for a message body, then this is all; for an attachment, the
 142 same procedure should be applied to the `Content-ID` header and it
 143 should be attached with a separating slash.
 144
 145 Finally, application environments (so, operating systems and browsers)
 146 usually are capable of doing something useful with a MIME-type. This is
 147 indeed taken into account.
 148
 149   [RFC 2392]: https://tools.ietf.org/html/rfc2392