Overview
This document describes the data structures and functional classes associated with the secure communication implementation.
class CConnection
Each open connection has a CConnection object associated with it. This controls how the connection behaves.
| void Set_to_Read_Encrypt (void) | public |
| Purpose: | Set a channel to decrypt messages received. |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void Set_to_Read_Authenticate (void) | public |
| Purpose: | Set a channel to authenticate received messages |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void Set_to_Read_Clear (void) | public |
| Purpose: | Set a channel to read messages as clear text |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void Set_to_Write_Encrypt (void) | public |
| Purpose: | Set a channel to send messages encrypted |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void Set_to_Write_Authenticate (void) | public |
| Purpose: | Set a channel to send messages with an authentication checksum |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void Set_to_Write_Clear (void) | public |
| Purpose: | Set a channel to write messages in the clear |
| Arguments: | None |
| Returns: | None |
| Notes: |
| void CConnection::ServerThread() | public |
| Purpose: | Creates a server thread for handling new and existing connections. Communicates with the security module to perform a handshake to establish a shared session key. |
| Arguments: | None |
| Returns: | None |
| Notes: |
class ssp_obj
| osock &get_connection() | public |
| Purpose: | Establishes a connection to a remote object. |
| Arguments: | None |
| Returns: | An open connection |
| Notes: | By default, an authenticated unencrypted channel is established. |
| osock &secure_connection(security_token_t &token) | public |
| Purpose: | Establishes an encrypted connection to a remote object. |
| Arguments: | token is a security token specifying |
| Returns: | An open connection |
| Notes: |
class ssp_reply
| osock &get_connection() | public |
| Purpose: | Establishes a connection to a remote object. |
| Arguments: | None |
| Returns: | An open connection |
| Notes: | By default, an authenticated unencrypted channel is established. |
| osock &secure_connection(security_token_t &token) | public |
| Purpose: | Establishes an encrypted connection to a remote object. |
| Arguments: | token is a security token specifying |
| Returns: | An open connection |
| Notes: |
class sock
sock is the base class for socket communication.
| void perdis_set_key(unsigned char *key) | public |
| Purpose: | Set the key for use in encryption and signing |
| Arguments: | key is an 8-byte DES key |
| Returns: | None |
| Notes: |
| int set_read_encrypt(void) | public |
| Purpose: | Set a channel to decrypt messages received. |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int set_read_authenticate(void) | public |
| Purpose: | Set a channel to authenticate received messages |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int set_read_clear(void) | public |
| Purpose: | Set a channel to read messages as clear text |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int set_write_encrypt(void) | public |
| Purpose: | Set a channel to send messages encrypted |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int set_write_authenticate(void) | public |
| Purpose: | Set a channel to send messages with an authentication checksum |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int set_write_clear(void) | public |
| Purpose: | Set a channel to write messages in the clear |
| Arguments: | None |
| Returns: | None |
| Notes: |
class isock
sock is the base class for socket communication.
| void isock::read_more() | public |
| Purpose: | Reads outstanding bytes from a socket stream. Decrypts the bytes where necessary, and verifies the integrity checksum if an authenticated channel. |
| Arguments: | None |
| Returns: | None |
| Notes: |
class osock
sock is the base class for socket communication.
| void osock::bip() | public |
| Purpose: | Writes outstanding bytes to the outgoing socket stream. Encrypts bytes where necessary, and generates the integrity checksum on an authenticated channel. |
| Arguments: | None |
| Returns: | None |
| Notes: |
class pd_security
pd_security is the main security module. Its access control functions are discussed in the access control documentation. Here we focus on the secure communication support functions.
An important data structure is used in the negotiation of secure channels:
class encryption_request_t
{
public:
unsigned char key[128];
principal_t peer_name;
site_id peer;
int nonce;
signature_t signature;
};
Contains the arguments for a secure channel request:
key contains the session key, encrypted in the recipients public
key.
peer_name specifes the name of the PD originating the connection
peer specifies the PerDiS site id for the originating PD.
nonce is a unique value used to avoid replay attacks
signature is a signed hash of the request, signed with the originator's
private key.
| int pd_security::encryption_start_handshake (iosock *so, site_id peer, unsigned char *key) | public |
| Purpose: | Establishes a secure connection between two PDs over a socket stream. |
| Arguments: | so is the socket over
which the session key and parameters is to be established.
peer is the PerDiS identifier for the peer to establish a connection with. key returns the session key established. |
| Returns: | +ve on success, -ve otherwise. |
| Notes: | Generates a new session key, and attempts
to locate the certificates and keys needed to negotiate a shared secret
key. If any component is missing, a clear-text channel is established.
Otherwise the key is sent to the remote peer, the remote peer's identity is authenticated, and the key generated is associated with the connection. |
| int pd_security::receive_encryption_handshake (iosock *s,unsigned char *key) | public |
| Purpose: | Establish a session key over a connection initiated by a remote peer. |
| Arguments: | s is a socket stream
on which a new connection has been received.
key returns the key negotiated |
| Returns: | -ve for a clear channel, +ve if a key is negotiated |
| Notes: | Calls establish_peer_encryption_key to do the negotiation |
| encryption_reply_t pd_security::establish_peer_encryption_key( encryption_request_t &request, unsigned char *out_key)) | public |
| Purpose: | Negotiates a shared session key with the initiator of a secure connection |
| Arguments: | request is a secure
connection request data structure as described above.
key returns the key negotiated. |
| Returns: | A suitable reply for the request. |
| Notes: | calls validate_encryption_request
to authenticate the claimed originator of the connection.
If valid, it decrypts the session key, and generates a signed response to authenticate itself back to the originator. |
| int pd_security::validate_encryption_request (encryption_request_t &request) | public |
| Purpose: | Authenticate the creator of a secure connection request. |
| Arguments: | request is a secure connection request data structure as described above. |
| Returns: | true if authenticated, false otherwise |
| Notes: | Verifies the signature on the request. |
| int pd_security::prepare_encryption_request (unsigned char *key, encryption_request_t &clear, principal_t &remotehostname) | public |
| Purpose: | Encrypts the session key and signs the request. |
| Arguments: | key is the session key
to be shared.
clear is an unsigned encryption request remotehostname is the name of the remote host |
| Returns: | zero on success, negative otherwise. |
| Notes: | Encrypts the session key using the public key of the principal specified in remotehostname. Constructs a request structure, places the encrypted session key and other details in it, and signs a hash of the structure using the originator's private key. |
| void seed_des_key(void) | public |
| Purpose: | Seeds the random number generator used to generate DES keys. |
| Arguments: | None |
| Returns: | None |
| Notes: |
| int pd_security::encryption_start_challenge(iosock *so, site_id peer, unsigned char *key) | public |
| Purpose: | Establishes a secure connection with a PD in the same domain. |
| Arguments: | so is a socket stream
over which the connection is to be established.
peer is the PerDiS site id of the remote site. key is not used |
| Returns: | zero on success, -ve otherwise |
| Notes: | Generates a challenge string and encrypts it with the domain key, and sends it to the remote site. Receives the response from the remote site and verifies the response. |
| int pd_security::receive_encryption_challenge (iosock *s,unsigned char *key) | public |
| Purpose: | respond to a connection request from a peer in the same domain. |
| Arguments: | s is the socket stream
the connection is to be negotiated on.
key is unused. |
| Returns: | zero on success, -ve otherwise. |
| Notes: |