|
| 1 | +# SSH Feature Documentation |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +The SSH feature enables secure Git operations over SSH protocol, providing an alternative to HTTPS for repository access. This implementation acts as a proxy between Git clients and the remote Git server (e.g., GitHub), with additional security and control capabilities. |
| 6 | + |
| 7 | +## Configuration |
| 8 | + |
| 9 | +The SSH feature can be configured in the main configuration file with the following options: |
| 10 | + |
| 11 | +```json |
| 12 | +{ |
| 13 | + "ssh": { |
| 14 | + "enabled": true, |
| 15 | + "port": 22, |
| 16 | + "hostKey": { |
| 17 | + "privateKeyPath": "./.ssh/host_key", |
| 18 | + "publicKeyPath": "./.ssh/host_key.pub" |
| 19 | + } |
| 20 | + } |
| 21 | +} |
| 22 | +``` |
| 23 | + |
| 24 | +### Configuration Options |
| 25 | + |
| 26 | +- `enabled`: Boolean flag to enable/disable SSH support |
| 27 | +- `port`: Port number for the SSH server to listen on (default is 22) |
| 28 | +- `hostKey`: Configuration for the server's SSH host key |
| 29 | + - `privateKeyPath`: Path to the private key file |
| 30 | + - `publicKeyPath`: Path to the public key file |
| 31 | + |
| 32 | +## Authentication Methods |
| 33 | + |
| 34 | +The SSH server supports two authentication methods: |
| 35 | + |
| 36 | +1. **Public Key Authentication** |
| 37 | + |
| 38 | + - Users can authenticate using their SSH public keys |
| 39 | + - Keys are stored in the database and associated with user accounts |
| 40 | + - Supports various key types (RSA, ED25519, etc.) |
| 41 | + |
| 42 | +2. **Password Authentication** |
| 43 | + - Users can authenticate using their username and password |
| 44 | + - Passwords are stored securely using bcrypt hashing |
| 45 | + - Only available if no public key is provided |
| 46 | + |
| 47 | +## Connection Handling |
| 48 | + |
| 49 | +The SSH server implements several features to ensure reliable connections: |
| 50 | + |
| 51 | +- **Keepalive Mechanism** |
| 52 | + |
| 53 | + - Regular keepalive packets (every 15 seconds) |
| 54 | + - Configurable keepalive interval and maximum attempts |
| 55 | + - Helps prevent connection timeouts |
| 56 | + |
| 57 | +- **Error Recovery** |
| 58 | + |
| 59 | + - Graceful handling of connection errors |
| 60 | + - Automatic recovery from temporary disconnections |
| 61 | + - Fallback mechanisms for authentication failures |
| 62 | + |
| 63 | +- **Connection Timeouts** |
| 64 | + - 5-minute timeout for large repository operations |
| 65 | + - Configurable ready timeout (30 seconds by default) |
| 66 | + |
| 67 | +## Git Protocol Support |
| 68 | + |
| 69 | +The SSH server fully supports Git protocol operations: |
| 70 | + |
| 71 | +- **Git Protocol Version 2** |
| 72 | + |
| 73 | + - Enabled by default for all connections |
| 74 | + - Improved performance and security |
| 75 | + |
| 76 | +- **Command Execution** |
| 77 | + - Supports all standard Git commands |
| 78 | + - Proper handling of Git protocol streams |
| 79 | + - Efficient data transfer between client and server |
| 80 | + |
| 81 | +## Security Features |
| 82 | + |
| 83 | +1. **Host Key Verification** |
| 84 | + |
| 85 | + - Server uses a dedicated host key pair for the initial handshake between git proxy and user |
| 86 | + - Keys are stored securely in the filesystem |
| 87 | + - This key pair is used to establish the secure SSH connection and verify the server's identity to the client |
| 88 | + |
| 89 | +2. **Authentication Chain** |
| 90 | + |
| 91 | + - Integrates with the existing authentication chain |
| 92 | + - Supports custom authentication plugins |
| 93 | + - Enforces access control policies |
| 94 | + |
| 95 | +3. **Connection Security** |
| 96 | + - Secure key exchange |
| 97 | + - Encrypted data transmission |
| 98 | + - Protection against common SSH attacks |
| 99 | + |
| 100 | +## Implementation Details |
| 101 | + |
| 102 | +The SSH server is implemented using the `ssh2` library and includes: |
| 103 | + |
| 104 | +- Custom SSH server class (`SSHServer`) |
| 105 | +- Comprehensive error handling |
| 106 | +- Detailed logging for debugging |
| 107 | +- Support for large file transfers |
| 108 | +- Efficient stream handling |
| 109 | + |
| 110 | +## Usage |
| 111 | + |
| 112 | +To use the SSH feature: |
| 113 | + |
| 114 | +1. Ensure SSH is enabled in the configuration |
| 115 | +2. Generate and configure the host key pair |
| 116 | +3. Add user SSH keys to the database |
| 117 | +4. Connect using standard Git SSH commands: |
| 118 | + |
| 119 | +```bash |
| 120 | +git clone git@your-proxy:username/repo.git |
| 121 | +``` |
| 122 | + |
| 123 | +If other than default (22) port is used, git command will look like this: |
| 124 | + |
| 125 | +```bash |
| 126 | +git clone ssh://git@your-proxy:2222/username/repo.git |
| 127 | +``` |
| 128 | + |
| 129 | +## Troubleshooting |
| 130 | + |
| 131 | +Common issues and solutions: |
| 132 | + |
| 133 | +1. **Connection Timeouts** |
| 134 | + |
| 135 | + - Check keepalive settings |
| 136 | + - Verify network connectivity |
| 137 | + - Ensure proper firewall configuration |
| 138 | + |
| 139 | +2. **Authentication Failures** |
| 140 | + |
| 141 | + - Verify SSH key format |
| 142 | + - Check key association in database |
| 143 | + - Ensure proper permissions |
| 144 | + |
| 145 | +3. **Performance Issues** |
| 146 | + - Adjust window size and packet size |
| 147 | + - Monitor connection timeouts |
| 148 | + - Check server resources |
| 149 | + |
| 150 | +## Development |
| 151 | + |
| 152 | +The SSH implementation includes comprehensive tests in `test/ssh/sshServer.test.js`. To run the tests: |
| 153 | + |
| 154 | +```bash |
| 155 | +npm test |
| 156 | +``` |
| 157 | + |
| 158 | +## Future Improvements |
| 159 | + |
| 160 | +Planned enhancements: |
| 161 | + |
| 162 | +1. Move SSH configuration options (keep alive, timeouts, and other params) to config file |
| 163 | +2. Enhance actions for SSH functionality |
| 164 | +3. Improved error reporting |
| 165 | +4. Additional security features |
0 commit comments