commit 137b80e403bf357dbddb90881630808cf83a4f83
from: Omar Polo <op@omarpolo.com>
date: Fri Feb 16 18:13:09 2024 UTC

add telescope-identity.1

commit - 9312e7a2a5b1b102c8713336eded822d0d001a2e
commit + 137b80e403bf357dbddb90881630808cf83a4f83
blob - /dev/null
blob + acff8f84ed05bf781b92d1a008f7a2ded6a2fab4 (mode 644)
--- /dev/null
+++ telescope-identity.1
@@ -0,0 +1,94 @@
+.\" Copyright (c) 2024 Omar Polo <op@omarpolo.com>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd $Mdocdate: February 16 2024$
+.Dt TELESCOPE-IDENTITY 1
+.Os
+.Sh NAME
+.Nm telescope-identity
+.Nd manage telescope identities
+.Sh SYNOPSIS
+.Nm
+.Bk -words
+.Ar command
+.Ar args...
+.Ek
+.Sh DESCRIPTION
+.Nm
+is an utility to manage
+.Xr telescope 1
+identities.
+Identities are TLS client certificates used for Gemini.
+.Pp
+The commands for
+.Nm
+are as follows:
+.Bl -tag -width generate
+.It Xo
+.Cm generate
+.Op Fl t Ar type
+.Ar name
+.Xc
+Generate a new keypair under the given
+.Ar name .
+If
+.Ar type
+is
+.Dq RSA ,
+an RSA key with 4096 bit will be created.
+By default it's an EC key with secp384r1.
+.It Cm remove Ar name
+Remove the
+.Ar name
+identity.
+.It Cm import Fl C Ar cert Oo Fl K Ar key Oc Ar name
+Imports a certificate as
+.Ar name .
+.Fl C
+is the path to the certificate itself.
+If the key is on a separate file, it needs to be passed with
+.Fl K .
+.It Cm export Fl C Ar cert Ar name
+Exports the certificate for the identity
+.Ar name .
+The certificate and the key will be saved at
+.Ar cert .
+At the moment, it's not possible to export the certificate and the
+private key in different files.
+.It Cm list
+Print one per line the available identities.
+.It Cm mappings Op Ar name
+Show on which servers and paths the identities are used.
+The output consist of the identity name, a tab character, and the the
+hostname, optional port number and path under which that identity will
+be loaded by
+.Xr telescope 1 .
+.Pp
+If
+.Ar name
+is given, limit the output only to the instances of that identity.
+.It Cm use Ar name Ar host Ns Oo : Ns Ar port Oc Ns Op / Ns Ar path
+Save the a new mapping for the given identity
+.Ar name .
+.It Cm forget Ar name Ar host Ns Oo : Ns Ar port Oc Ns Op / Ns Ar path
+Remove the mapping for the given identity
+.Ar name .
+.El
+.Sh SEE ALSO
+.Xr telescope 1
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+utility was written by
+.An Omar Polo Aq Mt op@omarpolo.com .