9. CreatePermission
TURN supports two ways for the client to install or refresh permissions on the server. This section describes one way: the CreatePermission request.
The CreatePermission request can be used in conjunction with the Send mechanism in Section 10 or with the channel mechanism in Section 11.
9.1. Forming a CreatePermission Request
A client wishing to install or refresh one or more permissions can send a CreatePermission request to the server.
When forming a CreatePermission request, the client MUST include at least one XOR-PEER-ADDRESS attribute and MAY include more than one such attribute. The IP address portion of each XOR-PEER-ADDRESS attribute contains the IP address for which a permission should be installed or refreshed. The port portion of each XOR-PEER-ADDRESS attribute will be ignored and can be any arbitrary value. The various XOR-PEER-ADDRESS attributes can appear in any order.
9.2. Receiving a CreatePermission Request
When the server receives a CreatePermission request, it processes it as per Section 4 plus the specific rules mentioned here.
The message is checked for validity. The CreatePermission request MUST contain at least one XOR-PEER-ADDRESS attribute and MAY contain multiple such attributes. If no such attribute exists, or if any of these attributes are invalid, then a 400 (Bad Request) error is returned. If the request is valid, but the server is unable to satisfy the request due to some capacity limit or similar, then a 508 (Insufficient Capacity) error is returned.
The server MAY impose restrictions on the IP address allowed in the XOR-PEER-ADDRESS attribute -- if a value is not allowed, the server rejects the request with a 403 (Forbidden) error.
If the message is valid and the server is capable of carrying out the request, then the server installs or refreshes a permission for the IP address contained in each XOR-PEER-ADDRESS attribute as described in Section 8. The port portion of each attribute is ignored and can be any arbitrary value.
The server then responds with a CreatePermission success response. There are no mandatory attributes in the success response.
NOTE: The server need not do anything special to implement idempotency of CreatePermission requests over UDP using the "stateless stack approach". Retransmitted CreatePermission requests will simply refresh the permissions.
9.3. Receiving a CreatePermission Response
If the client receives a valid CreatePermission success response, then the client updates its data structures to indicate that the permissions have been installed or refreshed.