Manual Installation on Linux

This guide provides step-by-step instructions for manually installing the Keychain Core C/C++ library and Python package on Linux systems. Use this approach when you need more control over the installation process or when the automated installer is not suitable for your environment.

For most users, we recommend using the automated bootstrap installer instead of manual installation. Manual installation requires more steps and careful attention to dependencies.

Prerequisites

System Requirements

Operating System Support: - Ubuntu 18.04 LTS or later - CentOS 7 or later / RHEL 7 or later - Debian 9 or later - Fedora 30 or later - Other Linux distributions with glibc 2.17 or later

Architecture Support: - x86_64 (Intel/AMD 64-bit) - arm64 (ARM 64-bit)

Required Tools

Before starting the installation, ensure you have the following tools installed:

Ubuntu/Debian
CentOS/RHEL/Fedora

sudo apt update
sudo apt install -y curl wget tar gzip sha256sum

# CentOS/RHEL
sudo yum install -y curl wget tar gzip coreutils

# Fedora
sudo dnf install -y curl wget tar gzip coreutils

Python Requirements (Optional)

If you plan to install the Python package:

Ubuntu/Debian
CentOS/RHEL/Fedora

sudo apt install -y python3 python3-pip python3-dev

# CentOS/RHEL
sudo yum install -y python3 python3-pip python3-devel

# Fedora
sudo dnf install -y python3 python3-pip python3-devel

Python Version Requirements: - Python 3.7 or later - pip3

Step 1: Download the C/C++ Library

Identify Your Platform

First, determine your platform architecture:

# Check your architecture
uname -m

# Check your Linux distribution
cat /etc/os-release

Download the Library Package

Navigate to the official Keychain Core releases and download the appropriate package for your platform:

# Set version and platform variables
export KEYCHAIN_VERSION="3.0.0-rc20"  # Replace with current version
export PLATFORM="linux-x64"           # or linux-arm64 for ARM systems

# Create download directory
mkdir -p ~/keychain-install
cd ~/keychain-install

# Download the C++ library package
curl -LO "https://keychain.jfrog.io/artifactory/keychain-core-prerelease-generic/keychain-cpp/${KEYCHAIN_VERSION}/keychain-cpp-release-${KEYCHAIN_VERSION}-${PLATFORM}.tar.gz"

# Download checksum file for verification
curl -LO "https://keychain.jfrog.io/artifactory/keychain-core-prerelease-generic/keychain-cpp/${KEYCHAIN_VERSION}/keychain-cpp-release-${KEYCHAIN_VERSION}-${PLATFORM}.tar.gz.sha256"

Verify Package Integrity

Always verify the downloaded package before installation:

# Verify the checksum
sha256sum -c "keychain-cpp-release-${KEYCHAIN_VERSION}-${PLATFORM}.tar.gz.sha256"

# You should see output like:
# keychain-cpp-release-3.0.0-rc19-linux-x64.tar.gz: OK

If the checksum verification fails, do not proceed with installation. Re-download the package or contact support.

Step 2: Install the C/C++ Library

Extract the Package

# Extract the package
tar -xzf "keychain-cpp-release-${KEYCHAIN_VERSION}-${PLATFORM}.tar.gz"

# Navigate to the extracted directory
cd "keychain-cpp-release-${KEYCHAIN_VERSION}-${PLATFORM}"

# List contents to verify extraction
ls -la

The extracted directory should contain: - scripts/ - Installation scripts - lib/ - Shared libraries - include/ - Header files - share/ - Documentation and examples - config/ - Configuration templates

Choose Installation Scope

You can install Keychain Core in two scopes:

User Installation (Recommended): - Installs to ~/.local/ (no root access required) - Only available to the current user - Easier to manage and remove

System Installation: - Installs to /usr/local/ (requires root access) - Available to all users on the system - Requires administrative privileges

Install the Library

User Installation
System Installation

# Navigate to the scripts directory
cd scripts

# Install to user directory (~/.local)
./install.sh --user

# Verify installation
ls ~/.local/lib/libkeychain*
ls ~/.local/include/keychain/

# Navigate to the scripts directory
cd scripts

# Install to system directory (/usr/local) - requires sudo
sudo ./install.sh --system

# Verify installation
ls /usr/local/lib/libkeychain*
ls /usr/local/include/keychain/

Configure Library Path

After installation, you need to configure your system to find the library:

User Installation
System Installation

# Add library path to your shell profile
echo 'export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc
echo 'export PKG_CONFIG_PATH="$HOME/.local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bashrc

# Reload your profile
source ~/.bashrc

# Test library loading
ldconfig -p | grep keychain

# Update system library cache
sudo ldconfig

# Test library loading
ldconfig -p | grep keychain

Verify C/C++ Installation

Create a simple test program to verify the installation:

# Create test directory
mkdir -p ~/keychain-test
cd ~/keychain-test

# Create a simple C++ test program
cat > test_keychain.cpp << 'EOF'
#include <iostream>
#include "keychain/keychain_headers.hpp"

int main() {
    try {
        auto version = keychain::gateway::version();
        std::cout << "Keychain Core version: " << version.string() << std::endl;
        return 0;
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return 1;
    }
}
EOF

Compile and test:

User Installation
System Installation

# Compile the test program
g++ -std=c++17 -I$HOME/.local/include test_keychain.cpp -L$HOME/.local/lib -lkeychain -o test_keychain

# Run the test
./test_keychain

# Compile the test program
g++ -std=c++17 -I/usr/local/include test_keychain.cpp -L/usr/local/lib -lkeychain -o test_keychain

# Run the test
./test_keychain

Step 3: Install the Python Package

Method 1: Install from PyPI Index (Recommended)

# Install from Keychain's PyPI index
pip3 install keychain-python==3.0.0rc6 \
  --index-url https://keychain.jfrog.io/artifactory/api/pypi/keychain-core-prerelease-pypi/simple \
  --user

# Verify installation
python3 -c "import keychain_python; print(f'Keychain Python version: {keychain_python.__version__}')"

Method 2: Download and Install Manually

If you prefer to download the package manually, you can install either the wheel file or the source distribution:

Option A: Install from Wheel (Binary Package)

# Download the Python wheel
curl -LO "https://keychain.jfrog.io/artifactory/keychain-core-prerelease-pypi/keychain-python/3.0.0rc6/keychain_python-3.0.0rc6-py3-none-any.whl"

# Install the downloaded wheel
pip3 install keychain_python-3.0.0rc6-py3-none-any.whl --user

# Verify installation
python3 -c "import keychain_python; print(f'Keychain Python version: {keychain_python.__version__}')"

Option B: Install from Source Distribution (For Source Inspection)

Some customers prefer to inspect the Python source code before installation. You can download and install the source distribution (tar.gz) instead:

# Download the Python source distribution
curl -LO "https://keychain.jfrog.io/artifactory/keychain-core-prerelease-pypi/keychain-python/3.0.0rc6/keychain-python-3.0.0rc6.tar.gz"

# Optional: Extract and inspect the source code
tar -xzf keychain-python-3.0.0rc6.tar.gz
ls keychain-python-3.0.0rc6/
# You can now inspect the source files in keychain-python-3.0.0rc6/

# Install directly from the tar.gz file
pip3 install keychain-python-3.0.0rc6.tar.gz --user

# Verify installation
python3 -c "import keychain_python; print(f'Keychain Python version: {keychain_python.__version__}')"

Installing from the source distribution allows you to review the Python source code before installation, which is important for security-conscious environments. The installation process is identical - pip can install directly from tar.gz files.

Verify Python Installation

Create a simple Python test:

# Create Python test file
cat > test_keychain.py << 'EOF'
#!/usr/bin/env python3
"""Test Keychain Python installation."""

try:
    import keychain_python
    from keychain_python import Gateway, SecurityLevel

    print(f"Keychain Python version: {keychain_python.__version__}")
    print("Python package imported successfully!")

    # Test basic functionality (requires config file)
    # Uncomment the following lines if you have a config file:
    # settings = Gateway.init("~/.keychain/config/keychain.json")
    # print("Gateway initialization successful!")

except ImportError as e:
    print(f"Import error: {e}")
    exit(1)
except Exception as e:
    print(f"Error: {e}")
    exit(1)

print("Python installation verification complete!")
EOF

# Run the test
python3 test_keychain.py

Step 4: Configuration

Create Configuration Directory

# Create configuration directory
mkdir -p ~/.keychain/config

# Copy example configuration (if available)
if [ -d ~/.local/share/keychain/config ]; then
    cp ~/.local/share/keychain/config/* ~/.keychain/config/
elif [ -d /usr/local/share/keychain/config ]; then
    cp /usr/local/share/keychain/config/* ~/.keychain/config/
fi

Basic Configuration

Create a basic configuration file:

# Create basic keychain.json configuration
cat > ~/.keychain/config/keychain.json << 'EOF'
{
    "database": {
        "path": "~/.keychain/keychain.db"
    },
    "network": {
        "enabled": true,
        "timeout": 30000
    },
    "security": {
        "default_security_level": "medium"
    }
}
EOF

Troubleshooting

Common Issues

Library Not Found Errors

If you encounter "library not found" errors:

# Check if library is installed
ls ~/.local/lib/libkeychain* 2>/dev/null || ls /usr/local/lib/libkeychain* 2>/dev/null

# Check LD_LIBRARY_PATH
echo $LD_LIBRARY_PATH

# Manually add library path
export LD_LIBRARY_PATH="$HOME/.local/lib:$LD_LIBRARY_PATH"
# OR for system installation:
# export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

Python Import Errors

If Python cannot import the keychain_python module:

# Check if package is installed
pip3 list | grep keychain

# Check Python path
python3 -c "import sys; print(sys.path)"

# Reinstall if necessary
pip3 uninstall keychain-python
pip3 install keychain-python==3.0.0rc6 \
  --index-url https://keychain.jfrog.io/artifactory/api/pypi/keychain-core-prerelease-pypi/simple \
  --user

Permission Errors

If you encounter permission errors during installation:

# For user installation, ensure you have write access to ~/.local
mkdir -p ~/.local/{lib,include,share}
chmod 755 ~/.local ~/.local/lib ~/.local/include ~/.local/share

# For system installation, use sudo
sudo ./install.sh --system

Version Conflicts

If you have multiple versions installed:

# Remove old versions
pip3 uninstall keychain-python

# Clean up old C++ installations
rm -rf ~/.local/lib/libkeychain*
rm -rf ~/.local/include/keychain/

# Reinstall clean versions
# Follow the installation steps above

Getting Help

If you continue to experience issues:

Check Installation Logs: Review any error messages during installation
Verify Prerequisites: Ensure all required tools and dependencies are installed
Check Compatibility: Verify your Linux distribution and architecture are supported
Contact Support: Reach out with specific error messages and system information

Next Steps

After successful installation:

Read the Quick Start Guide: Follow the First Steps tutorial to create your first Keychain application
Explore Examples: Check the installed examples in ~/.local/share/keychain/examples/ or /usr/local/share/keychain/examples/
Review API Documentation: Familiarize yourself with the C++ API and Python API documentation
Configure Your Application: Set up appropriate configuration files for your use case

Uninstallation

To remove Keychain Core from your system:

Remove Python Package

pip3 uninstall keychain-python

Remove C/C++ Library

User Installation
System Installation

# Remove library files
rm -rf ~/.local/lib/libkeychain*
rm -rf ~/.local/include/keychain/
rm -rf ~/.local/include/tkcrypt/
rm -rf ~/.local/share/keychain/

# Remove from shell profile
sed -i '/LD_LIBRARY_PATH.*\.local\/lib/d' ~/.bashrc
sed -i '/PKG_CONFIG_PATH.*\.local\/lib/d' ~/.bashrc

# Remove library files (requires sudo)
sudo rm -rf /usr/local/lib/libkeychain*
sudo rm -rf /usr/local/include/keychain/
sudo rm -rf /usr/local/include/tkcrypt/
sudo rm -rf /usr/local/share/keychain/

# Update library cache
sudo ldconfig

Remove Configuration (Optional)

# Remove configuration and data (optional)
rm -rf ~/.keychain/

This completes the manual installation and uninstallation procedures for Keychain Core on Linux systems.