How to use secure RSA authentication with the Asterisk IAX2 channel
The IAX2 protocol supports strong authentication with asymmetric encryption keys, using RSA. This enables you to authenticate a user (someone that places calls in to your PBX) and authenticate your PBX to a peer when calling out to the peer.
Quote from res_krypto.c:
Asterisk uses RSA keys with SHA-1 message digests for its digital signatures. The choice of RSA is due to its higher throughput on verification, and the choice of SHA-1 based on the recently discovered collisions in MD5’s compression algorithm and recommendations of avoiding MD5 in new schemes from various industry experts.
We use OpenSSL to provide our crypto routines, although we never actually use full-up SSL
Creating keys
RSA encryption keys can be generated with the astgenkey utility included in the Asterisk asterisk/contrib/scripts directory. The script will generate the files {name}.pub and {name}.key in the script’s working directory which are the public and private keys, respectively. By default, Asterisk will look for these files in the /var/lib/asterisk/keys directory, so copy them there and make sure only the asterisk user id can read the keys and that no one can write over them.
Protect the private key strongly; never distribute it to other computers or make it accessible to users of the Linux system.
The astgenkey utility by default creates keys protected by a passphrase, a password you have to enter each time they’re used (or once when asterisk is started if you start Asterisk with the -i option.) To avoid needing the passphrase, which prevents unattended restarts and reboots of your PBX, use astgenkey with the -n switch, which creates keys without passphrases.
openssl genrsa -out ${KEY}.key -des3 1024
to this (remove the -des3 part):
openssl genrsa -out ${KEY}.key 1024
WARNING: If you do not force the use of a passphrase, the key file needs to be protected carefully. While you’ll make life a bit easier for yourself by disabling the key password, so will you likewise do for anyone that gets their hands on the key file.
CLI commands
- Add the ‘-i’ flag to the asterisk command line if you want to automatically initialize passcodes at launch.
init keys: Initalizes the RSA keys and prompts for passwords if needed
- Show keys: Displays RSA key information
(so what are the commands?)
Dialing syntax
With RSA keys
IAX2/[<user>:[name-of-key]@]<peer>[:<portno>][/<exten>[@<context>][/<options>]]
The [] parameters around the key name are verbatim, they need to be there. The key name is the name of the key files minus the extension (.key and .pub).
Assigning key sets in IAX.conf
For each IAX client, you may designate a key pair for authentication.
Declaration of IAX2 user with RSA key authentication
A peer receives calls. The following would be needed in iax.conf on the peer machine to verify (authenticate) the identify of the user before allowing calls from that user. This is done using the user’s public key.
type=user
auth=rsa
inkeys=name-of-the-public-key
context=iax2users
Declaration of IAX2 peer with RSA key authentication
A user makes calls. The following would be needed in iax.conf on the user machine to identify (authenticate) itself to the peer before the peer will take the call. This is done with this user’s private key. The user must make sure to provide the peer a copy of the user’s public key (.pub). The user’s private key (.key) is never sent to anyone but instead remains hidden safely in the user’s Asterisk key directory.
type=peer
host=hostname.domain.tld
auth=rsa
outkey=name_of_your_key_set ; redundant if already embedded in Dial string
username=username-at-the-host ; redundant if already embedded in Dial string
Further reading on this topic
- Asterisk | Channels | Configuration | FAQ
April 7, 2023
Phone System 