install_prereq: Download latest Jansson.
[asterisk/asterisk.git] / contrib / scripts / astgenkey.8
1 .\" $Header$
2 .\"
3 .\"     transcript compatibility for postscript use.
4 .\"
5 .\"     synopsis:  .P! <file.ps>
6 .\"
7 .de P!
8 .fl
9 \!!1 setgray
10 .fl
11 \\&.\"
12 .fl
13 \!!0 setgray
14 .fl                     \" force out current output buffer
15 \!!save /psv exch def currentpoint translate 0 0 moveto
16 \!!/showpage{}def
17 .fl                     \" prolog
18 .sy sed \-e 's/^/!/' \\$1\" bring in postscript file
19 \!!psv restore
20 .
21 .de pF
22 .ie     \a\\*(f1\a\a .ds f1 \\n(.f
23 .el .ie \a\\*(f2\a\a .ds f2 \\n(.f
24 .el .ie \a\\*(f3\a\a .ds f3 \\n(.f
25 .el .ie \a\\*(f4\a\a .ds f4 \\n(.f
26 .el .tm ? font overflow
27 .ft \\$1
28 ..
29 .de fP
30 .ie     !\a\\*(f4\a\a \{\
31 .       ft \\*(f4
32 .       ds f4\"
33 '       br \}
34 .el .ie !\a\\*(f3\a\a \{\
35 .       ft \\*(f3
36 .       ds f3\"
37 '       br \}
38 .el .ie !\a\\*(f2\a\a \{\
39 .       ft \\*(f2
40 .       ds f2\"
41 '       br \}
42 .el .ie !\a\\*(f1\a\a \{\
43 .       ft \\*(f1
44 .       ds f1\"
45 '       br \}
46 .el .tm ? font underflow
47 ..
48 .ds f1\"
49 .ds f2\"
50 .ds f3\"
51 .ds f4\"
52 '\" t
53 .ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
54 .TH ASTGENKEY 8 "May 14th, 2005" "Asterisk" "Linux Programmer's Manual"
55 .SH NAME
56 .B astgenkey \- generates keys for for Asterisk IAX2 RSA authentication
57 .SH SYNOPSIS
58 .PP
59 .B astgenkey
60 [ \-q ] [ \-n ] [ \fIkeyname\fP ]
61
62 .SH DESCRIPTION
63 .B astgenkey
64 This script generates an RSA private and public key pair in PEM format
65 for use by Asterisk.  The private key should be kept a secret, as it can
66 be used to fake your system's identity.  Thus by default (without the
67 option
68 .I \-n
69 ) the script will create a passphrase-encrypted copy of your secret key:
70 without entering the passphrase you won't be able to use it.
71
72 However if you want to use such a key with Asterisk, you'll have to start
73 it interactively, because the scripts that start asterisk can't use that
74 encrypted key.
75
76 The key is identified by a name. If you don't write the name on the
77 command-line you'll be prompted for one. The outputs of the script are:
78
79 .I name\fB.pub
80 .RS
81 The public key: not secret. Send this to the other side.
82 .RE
83
84 .I name\fB.key
85 .RS
86 The private key: secret.
87 .RE
88
89 Those files should be copied to
90 .I /var/lib/asterisk/keys
91
92 (The private key: on your system. The public key: on other systems)
93
94 To see the currently-installed keys from the asterisk CLI, use the command
95
96 .RS
97 keys show
98 .RE
99
100 .SH OPTIONS
101 .B \-q
102 .RS
103 Run quietly.
104 .RE
105
106 .B \-n
107 .RS
108 Don't encrypt the private key.
109 .RE
110
111 .SH SECURITY
112 The keys are created, using the umask of the user running the command.
113 To create the keys in a secure manner, you should check to ensure that
114 your umask is first set to disallow the private key from being world-
115 readable, such as with the following commands:
116
117 .I umask 0066
118
119 .I astgenkey yourkey
120
121 And then make the key accessible to Asterisk (assuming you run it as
122 user "asterisk").
123
124   chown asterisk /var/lib/asterisk/keys/yourname.*
125
126 .SH FILES
127 .I /var/lib/asterisk/keys
128 .RS
129 .RE
130
131 .SH "SEE ALSO"
132 asterisk(8), genrsa(1), rsa(1),
133
134 http://www.voip\-info.org/wiki\-Asterisk+iax+rsa+auth
135
136 .SH "AUTHOR"
137 This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com>
138 Permission is granted to copy, distribute and/or modify this document under
139 the terms of the GNU General Public License, Version 2 any
140 later version published by the Free Software Foundation.
141
142 On Debian systems, the complete text of the GNU General Public
143 License can be found in /usr/share/common\-licenses/GPL\-2.