Linking according to specification (aka new PSYC)
Linking to an Identity
The main purpose for a location (usually a user's client) to be on the PSYC network is to get linked to one or several identities (usually a person entity) in order to be able to execute commands or send messages on its behalf. The location application was probably given a UNI, so it needs to resolve that uniform in order to create a circuit to it, then negotiate a link to it, which is done by subscribing to the links channel of the UNI.
The packet has to be _targeted at the UNI and optionally provide a UNL as _source. This is an example:
| :_target psyc://example.org/~fippo#_links :_tag 284232 _request_context_enter |
It uses the context subscription protocol as defined earlier. When (after authentication) the link could be established, typically a _notice_context_enter packet is multicast from the identity to all subscribed locations. The _source variable must contain the UNI (the identity's uniform) and the _target variable the UNL (the location's uniform):
| :_source psyc://example.org/~fippo#_links :_target psyc://ente.aquarium:-32872 :_tag_relay 284232 _notice_context_enter |
Plain password authentication
If there is no security issue with a password traveling the wire in the clear, you can just set the _password variable when sending the _request_link packet:
| :_target psyc://example.org/~fippo#_links :_tag 284232 :_password godsecretXX332 _request_context_enter |
Hash based authentication
In order for the identity to check whether the _source of the _request_link is allowed to link it sends a _request_password packet to the _source as reply to the _request_link packet. The reply contains a _nonce variable that is used to do hash-based authentication as follows as well as a _password variable with the ? query operator.
Such a _request_password packet may look like this:
| :_source psyc://example.org/~fippo#_links :_target psyc://ente.aquarium:-32872 :_tag_relay 284232 :_available_hashes |sha1|md5 :_nonce 6eaa3554 _error_necessary_authentication Please show identification. |
You should proceed by sending a _request_context_enter again with the variable _method set to the hash function used and _password containing the hex encoded hash of the nonce and the password, concatenated.
The hash function to use can be chosen from the list in _available_hashes, which is one of these:
- sha1 - SHA1 hash algorithm
- md5 - MD5 hash algorithm
Such a packet may look like this:
| :_source psyc://ente.aquarium:-32872 :_target psyc://example.org/~fippo#_links :_tag 984383 :_method sha1 :_password 68fe60d9b3989848c39842bb3038f515bf7979d3 _request_context_enter |
The password field in the reply contains sha1(nonce + password) = sha1('6eaa3554xfippox') = '68fe60d9b3989848c39842bb3038f515bf7979d3'. The + operator in this case is intended as string concatenation. Note that you don't need to resend the _nonce.
If the password was correct you will receive a _notice_link as described earlier. But if the password was wrong a _error_invalid_password packet is generated as response, which looks similar to this:
| :_source psyc://example.org/~fippo#_links :_target psyc://ente.aquarium:-32872 :_tag_relay 984383 _error_invalid_password Wrong password for [_source]! |
Unlinking from a Person Entity
If you want to unlink from the person entity again send a packet with _request_context_leave method, according to the context subscription protocol.
Current (aka old) psyced client linking procedure
Linking a UNI
By requesting a link you request an authoritative controlling type of connection to the entity, not just entering it. Although this could still be seen as a special case of entering in the grand scheme of subscription, it currently isn't. Here's the typical procedure of a client linking to its user's UNI.
. =_target psyc://fi.ve.symlynx.com/~fippo _request_link .
. :_source psyc://fi.ve.symlynx.com/~fippo :_target psyc://ente.aquarium:-32872 :_nick fippo _info_nickname Hello [_nick]. .
Note that there is no more explicit target sent in the following packets, they are assumed to be added on client side by the state machine. If a password for the account is set, you will be queried to supply it:
. :_source psyc://fi.ve.symlynx.com/~fippo :_target psyc://ente.aquarium:-32872 :_nonce 6eaa3554 _query_password Please show identification. .
Here's one way to deliver the password:
. :_password xfippox :_tag whatever _request_link .
You may however want to not transmit the password in clear text over the wire. In this case you can apply a hashing method to the concatenated list of _nonce and _password. On reply you must supply the the _method used (any of the strings listed in _available_methods_hash) and the resulting hash in _password, still using the _request_link mc. You should not supply the _nonce again and the server must not make use of any _nonce supplied in the reply.
. :_method sha1 :_tag whatever :_password 68fe60d9b3989848c39842bb3038f515bf7979d3 .
The password field contains sha1(nonce + password) = sha1('6eaa3554xfippox') = '68fe60d9b3989848c39842bb3038f515bf7979d3'. The + operator in this case is intended as string concatenation. Note that you don't need to resend the _nonce.
Reasoning: By using the challenge from the server contained in the nonce, you are making a unique temporary variant of the password valid only now and only once, so an attacker cannot reuse it later (She can still steal your TCP connection though, if she has access to any intermediate routing device. To protect yourself from that you need encryption like TLS). This part is supposed to become conformant to SASL, by the way.
If your request suceeds you will see something like
. :_source psyc://fi.ve.symlynx.com/~fippo :_target psyc://ente.aquarium:-32872 :_tag_reply whatever :_nick fippo _notice_link You are now connected to this big marshmellow in the sky. .
Congratulations, you have just entered PSYCspace.