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
 |

Authentication

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.