1 .\" Copyright (c) 2024 Omar Polo <op@omarpolo.com>
2 .\"
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
6 .\"
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 .Dd $Mdocdate: February 16 2024$
15 .Dt TELESCOPE-IDENTITY 1
16 .Os
17 .Sh NAME
18 .Nm telescope-identity
19 .Nd manage telescope identities
20 .Sh SYNOPSIS
21 .Nm
22 .Bk -words
23 .Ar command
24 .Ar args...
25 .Ek
26 .Sh DESCRIPTION
27 .Nm
28 is an utility to manage
29 .Xr telescope 1
30 identities.
31 Identities are TLS client certificates used for Gemini.
32 .Pp
33 The commands for
34 .Nm
35 are as follows:
36 .Bl -tag -width generate
37 .It Xo
38 .Cm generate
39 .Op Fl t Ar type
40 .Ar name
41 .Xc
42 Generate a new keypair under the given
43 .Ar name .
44 If
45 .Ar type
46 is
47 .Dq RSA ,
48 an RSA key with 4096 bit will be created.
49 By default it's an EC key with secp384r1.
50 .It Cm remove Ar name
51 Remove the
52 .Ar name
53 identity.
54 .It Cm import Fl C Ar cert Oo Fl K Ar key Oc Ar name
55 Imports a certificate as
56 .Ar name .
57 .Fl C
58 is the path to the certificate itself.
59 If the key is on a separate file, it needs to be passed with
60 .Fl K .
61 .It Cm export Fl C Ar cert Ar name
62 Exports the certificate for the identity
63 .Ar name .
64 The certificate and the key will be saved at
65 .Ar cert .
66 At the moment, it's not possible to export the certificate and the
67 private key in different files.
68 .It Cm list
69 Print one per line the available identities.
70 .It Cm mappings Op Ar name
71 Show on which servers and paths the identities are used.
72 The output consist of the identity name, a tab character, and the the
73 hostname, optional port number and path under which that identity will
74 be loaded by
75 .Xr telescope 1 .
76 .Pp
77 If
78 .Ar name
79 is given, limit the output only to the instances of that identity.
80 .It Cm use Ar name Ar host Ns Oo : Ns Ar port Oc Ns Op / Ns Ar path
81 Save the a new mapping for the given identity
82 .Ar name .
83 .It Cm forget Ar name Ar host Ns Oo : Ns Ar port Oc Ns Op / Ns Ar path
84 Remove the mapping for the given identity
85 .Ar name .
86 .El
87 .Sh SEE ALSO
88 .Xr telescope 1
89 .Sh AUTHORS
90 .An -nosplit
91 The
92 .Nm
93 utility was written by
94 .An Omar Polo Aq Mt op@omarpolo.com .