PDMSC live test service: licensing and your API key
====================================================

BEFORE YOU START: the live service is for individuals and for evaluation and testing only, and it
works by sending each message you scan, in full, off your system to live.pdmsc.com. Read TERMS.txt
first. If that does not suit your mail, do not enable it.

Two different licences are involved. The module in this package is free software under the BSD
2-Clause licence (COPYRIGHT): copy and modify it freely. The live SERVICE is separate and needs
a key, as described below.

The live service uses the same licence system as the PDMSC daemon. A message is only
scored for you if your key belongs to an ACTIVE PDMSC licence.

How it fits together
--------------------
    Company  ->  Licence (active)  ->  API key (pdl_...)  ->  pdmsc-live-setup  ->  rspamd

  * A COMPANY is your organisation's account on the PDMSC licence service.
  * A LICENCE is what entitles it to use PDMSC. It has a term and a number of seats.
  * An API KEY is what your rspamd presents to live.pdmsc.com. It is tied to one licence.
    Create one key per site or server, so you can revoke one without touching the others.

1. Get an account
-----------------
Accounts are created by invitation. Email enquiries@misullivan.com and say you would like
to try the live service (subject "PDMSC licence"). We will create your company and a licence
for the trial, and send an email invitation. Open the link in it to confirm your email
address and choose a password.

2. Check your licence
---------------------
Sign in at  https://license.pdmsc.com  and open your company. Under "Licences" you should see
an entry with status  active  and an expiry date. If it says pending, we have not finished
setting it up yet. If you need more seats, or a longer term, use "Request licence" on the same page.
(Owners and admins can request licences and create keys; members can only view.)

3. Create an API key
--------------------
On your company page, go to "API keys":

    Label    a name you will recognise, for example the server's name
    Licence  choose your ACTIVE licence from the list
    then click "Create API key".

The key is shown ONCE, starting with  pdl_ . Copy it now. If you lose it, revoke it and create
another. IMPORTANT: choose the licence. A key that is not tied to an active licence is
refused by the live service ("licence no_licence").

4. Put the key into rspamd
--------------------------
With the PDMSC live package installed, run as root:

    pdmsc-live-setup --key pdl_YOUR_KEY_HERE --reload

or let it ask for the key (nothing is shown on screen, nothing is left in your shell history):

    pdmsc-live-setup

The key is stored in one file (/etc/rspamd/pdmsc_live.key, readable only by root and the
rspamd group) and is never written into rspamd's configuration. The tool then tests the
configuration with rspamadm and, with --reload, reloads rspamd.

5. Check it works
-----------------
    pdmsc-live-setup --test

This sends a harmless sample message to live.pdmsc.com and tells you in plain words whether
your key and licence are accepted (HTTP 200), or why not:

    401  the key is not accepted: copied wrongly, or revoked
    403  the key is fine but the licence is not valid: expired, suspended, revoked, or the
         key was created without choosing an active licence
    429  too many requests: wait a few seconds
    503  the service is busy: try again

Real mail then shows PDMSC_* symbols in rspamd's results (X-Spamd-Result). By default they
score 0 ("mirror mode"), so nothing about your mail handling changes. When you are happy,
turn the scores on:

    pdmsc-live-setup --scored --reload

6. Rotate or revoke a key
-------------------------
In the portal, "API keys" > "Revoke" on the old key, create a new one, then run
pdmsc-live-setup --key pdl_NEW_KEY --reload. A revoked key stops working within about a minute.

7. What happens when something is wrong
---------------------------------------
Licence trouble can stop PDMSC scoring. It can never stop your mail. If the key is refused, the
licence has expired, or live.pdmsc.com cannot be reached, the module adds a score-0 "FAIL"
symbol that says why (for example  PDMSC_S1_FAIL  "licence expired") and your mail is delivered
exactly as it would have been.

Limits and privacy
------------------
  * 30 messages a minute per key (bursts of 10), one scan at a time per key, messages up to 2 MiB.
  * The WHOLE message (headers, body, attachments) leaves your system: it is sent to
    live.pdmsc.com over HTTPS and scored in memory; it is not kept and not written to temporary files. Our log records only the
    key id, message size, timings and verdict classes. Do not send mail that must not leave
    your network or that you have no right to share.
  * Our staff do not intercept or read your messages. If you want that in writing, we are happy
    to sign a general-purpose NDA covering your test data: write to enquiries@misullivan.com.
  * For individuals and for evaluation and testing only; not for production mail flow. The full
    terms are in TERMS.txt; using a key means you accept them.
  * Pricing and the general licensing terms are on https://www.pdmsc.com/licensing.html .

Questions: enquiries@misullivan.com
