Issue and share a certificate

Before you start#

A certificate is made from a finished check that tried your agent's tasks. If you have not run one, start with Check your agent. The certificate is about the code and settings as they were when the check ran.

A certificate you issue is signed with a key made on your own computer. That shows nobody changed it. It does not show who issued it, and it is not an independent assessment. See Prove and certificates.

Read the draft#

1. Open the Certificate room.
2. Look at the card in the Draft state. It says "This is a draft built from the latest finished check. Nothing is signed until you issue it." Nothing is stored for a draft, and it can never be exported as a certificate.
3. Read the three gauges: assessment, integrity and applicability. Press Read it in full to see the report rule by rule and what was not reached.
4. Press Preview as a reviewer to see the page a recipient would open, before anything leaves your computer.

Issue it#

Press Issue the certificate. Geometer signs the report with your computer's key and stores it. The card moves to the Issued state, and the integrity gauge reads signed, with a note that it is signed on this computer. Issuing again for the same check returns the same report.

To also sign with the newer post-quantum method, create the report on the Reports screen (Create report) with Also sign with the newer post-quantum method turned on. It is off by default, makes a larger file, and the person checking needs both of your computer's public keys. In a terminal, geo assessment create --profile hybrid does the same.

geo assessment create
geo assessment list
geo assessment show <id>

Share it#

Press Share as a pack. Geometer writes a folder in its own records folder, never in your project. It holds a page you can read without Geometer or a network (index.html, with the three gauges as separate sections and no script), the evidence that may leave your computer, and a file for checking the report. Private evidence stays on your computer. Anything that looks like a password or key is withheld.

To share publicly, use Export a copy to share publicly on the Reports screen. It makes a separate copy, with its own name, with all private evidence left out. The original report is not changed. In a terminal:

geo assessment export <id> --out ./share
geo assessment export <id> --out ./share-public --public

Add --include-private to the first command only if the recipient may see private evidence.

Give the recipient the folder and your public key by a route they trust, for example geo assessment key --out <where to save the key>. They check the report with the open verifier or with geo assessment verify. See Verify records yourself.

Share a link#

A link lets someone open your certificate in a browser without installing anything. It is opt in, one certificate at a time. Nothing is uploaded unless you press Publish a link on that certificate, or run geo certificate publish. Certificate links are built but not switched on yet: until Geometer sets up the service, Publish shows you the preview and then says there is nowhere to publish to. If you run your own service you can publish to it with --to.

geo certificate publish <id>
geo certificate publish <id> --preview
geo certificate unpublish <id>
geo certificate published

Before anything is sent, you see exactly what will be uploaded: every file and its size, the report's title, the rules it names and the code version (these can reveal what your project is), the issuer key's four-word fingerprint, and three sentences: anyone with the link can read it; it stays until you remove it; Geometer stores it and did not check it. Then you confirm. In a script, --yes confirms and the preview is still printed. The upload is the same bytes the preview was built from; if the certificate changed in between, it is refused.

What is public. The separate public copy of the certificate (private evidence left out, anything that looks like a password or key withheld), the evidence allowed to leave your computer, the signed status, your public key and key log, and a random id of this computer inside the signed status entries. What is not. Private evidence, your project folder, file paths on your computer, the Prove record, call details and your secret key. There is no name, email or account.

Who it is published by. You, the builder. The page says "Stored by Geometer. Geometer did not check this certificate." It never says certified or verified by Geometer. The link ends in #k= and your key's id: the part after # is never sent to the server, and it lets the reader's browser confirm the key is the one you meant. Give the reader the issuer's key by another route, as for a shared pack.

What the page checks. In the reader's browser it checks that the stored bytes match the link, that the key you published with sent them, and that the key is the one in the link. It does not yet check the certificate's own signature or its rules; for that, download the file and run geo-verify assessment with your key (see Verify records yourself).

Remove it. geo certificate unpublish <id> (or Remove the link) sends a delete signed with the certificate's key. No account or password is involved; only that key can remove it. The page then says the publisher removed it, and only the id and the time of removal are kept. Copies someone already saved cannot be recalled, and a cached copy can show for a few minutes. If you have lost the key, write to [email protected].

Track whether it still applies#

When your code changes after you issue a certificate, the applicability gauge changes to changed, and the next step on the board becomes Recheck what changed. Press it to run an ordinary check. The old certificate's results are never rewritten. To get a new certificate, issue it from the new check.

A few commands keep a report's status honest:

• geo assessment status <id> shows the signed status: issued, replaced, marked as no longer applying or withdrawn.
• geo assessment withdraw <id> --reason "..." records that you no longer stand behind the report. Its results are kept as they were.
• geo assessment invalidate <id> --because subject_changed --reason "..." marks it as no longer applying because something changed. The reasons are subject_changed, rule_changed, config_changed, environment_changed, dependency_changed, model_changed, policy_changed and exception_changed.
• geo assessment renew <id> keeps today's check of the report with a fresh signed status and an anchor of the record.

To have Geometer start the recheck for you, see Recheck automatically when the code changes.

The dated export for auditors#

In Prove, A dated export for auditors collects the certificates, grants, ceilings, step-downs and Guard's record as they stood on a date, in one folder on your computer. Nothing is sent anywhere.

1. Choose the date in As of. It defaults to today.
2. Press Export.
3. Geometer shows a sentence about what it wrote, the folder, and a list of files.

The folder is under Geometer's records folder (in exports/), never in your project. It holds:

The date cuts the certificates and Guard's summary. Prove's evidence and the authority records are exported whole, each with its own time, and the README says so. The export cannot answer anything outside Guard, or whether the agent behaved correctly in production.

• Recheck automatically when the code changesLet Geometer notice a change.
• Verify records yourselfWhat a recipient can check.