AcmeshWrapper 1.1.0

AcmeshWrapper

English | Türkçe

English

Description

AcmeshWrapper is a modern .NET library that provides a type-safe, async wrapper around the popular acme.sh ACME protocol client. It simplifies the process of obtaining, renewing, and managing SSL/TLS certificates from Let's Encrypt and other ACME-compliant certificate authorities in your .NET applications.

Features

• Type-safe API: Strongly-typed options and results for all acme.sh commands
• Async/await support: All operations are fully asynchronous
• Comprehensive command coverage:
  • list - List all certificates
  • issue - Issue new certificates
  • renew - Renew specific certificates
  • renew-all - Renew all certificates due for renewal
  • install-cert - Install certificates to specific locations
  • revoke - Revoke certificates
  • remove - Remove certificates from acme.sh management
  • info - Get detailed certificate information
  • get-certificate - Retrieve certificate file contents
• Error handling: Detailed error information with structured results
• Cross-platform: Works on Windows, Linux, and macOS
• Minimal dependencies: Built on ProcessX for reliable process execution

Requirements

• .NET Standard 2.1 or .NET 9.0
• acme.sh installed and accessible in PATH
• Appropriate permissions for certificate operations

Installation

# Install via NuGet
dotnet add package AcmeshWrapper

Quick Start

using AcmeshWrapper;

// Create client
var client = new AcmeClient();

// List certificates
var result = await client.ListAsync(new ListOptions { Raw = true });
foreach (var cert in result.Certificates)
{
    Console.WriteLine($"{cert.Domain} - Expires: {cert.Le_Next_Renew_Time}");
}

Usage Examples

Creating an AcmeClient

using AcmeshWrapper;

// Default constructor uses "acme.sh" from PATH
var client = new AcmeClient();

// Or specify custom path
var client = new AcmeClient("/usr/local/bin/acme.sh");

Listing Certificates

var listOptions = new ListOptions
{
    Raw = true // Get raw output format
};

var result = await client.ListAsync(listOptions);

if (result.IsSuccess)
{
    foreach (var cert in result.Certificates)
    {
        Console.WriteLine($"Domain: {cert.Domain}");
        Console.WriteLine($"Next Renewal: {cert.Le_Next_Renew_Time}");
        Console.WriteLine($"Key Length: {cert.Le_Keylength}");
    }
}
else
{
    Console.WriteLine("Error listing certificates:");
    foreach (var error in result.ErrorOutput)
    {
        Console.WriteLine(error);
    }
}

Issuing a New Certificate

var issueOptions = new IssueOptions
{
    Domains = new List<string> { "example.com", "www.example.com" },
    WebRoot = "/var/www/html",
    KeyLength = "4096",
    Staging = false // Use true for testing
};

var result = await client.IssueAsync(issueOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Certificate: {result.CertificateFile}");
    Console.WriteLine($"Key: {result.KeyFile}");
    Console.WriteLine($"CA: {result.CaFile}");
    Console.WriteLine($"Full Chain: {result.FullChainFile}");
}

Renewing a Certificate

var renewOptions = new RenewOptions
{
    Domain = "example.com",
    Force = false, // Force renewal even if not due
    Ecc = false    // Use ECC certificate
};

var result = await client.RenewAsync(renewOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Renewed at: {result.RenewedAt}");
    Console.WriteLine($"Certificate: {result.CertificatePath}");
}

Installing Certificates

var installOptions = new InstallCertOptions
{
    Domain = "example.com",
    CertFile = "/etc/nginx/ssl/cert.pem",
    KeyFile = "/etc/nginx/ssl/key.pem",
    FullChainFile = "/etc/nginx/ssl/fullchain.pem",
    ReloadCmd = "systemctl reload nginx"
};

var result = await client.InstallCertAsync(installOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Installed at: {result.InstalledAt}");
    Console.WriteLine($"Reload executed: {result.ReloadCommandExecuted}");
}

Revoking a Certificate

var revokeOptions = new RevokeOptions
{
    Domain = "example.com",
    Reason = RevokeReason.KeyCompromise
};

var result = await client.RevokeAsync(revokeOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Revoked at: {result.RevokedAt}");
    Console.WriteLine($"Thumbprint: {result.CertificateThumbprint}");
}

Renewing All Certificates

var renewAllOptions = new RenewAllOptions
{
    StopRenewOnError = true // Stop if any renewal fails
};

var result = await client.RenewAllAsync(renewAllOptions);

Console.WriteLine($"Total certificates: {result.TotalCertificates}");
Console.WriteLine($"Successful renewals: {result.SuccessfulRenewals}");
Console.WriteLine($"Skipped (not due): {result.SkippedRenewals}");
Console.WriteLine($"Failed: {result.FailedRenewals}");

if (result.FailedDomains.Any())
{
    Console.WriteLine("Failed domains:");
    foreach (var domain in result.FailedDomains)
    {
        Console.WriteLine($"  - {domain}");
    }
}

Removing a Certificate

var removeOptions = new RemoveOptions
{
    Domain = "example.com",
    Ecc = false
};

var result = await client.RemoveAsync(removeOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Removed: {result.Domain} at {result.RemovedAt}");
}

Getting Certificate Information

var infoOptions = new InfoOptions
{
    Domain = "example.com",
    Ecc = false // Set to true for ECC certificates
};

var result = await client.InfoAsync(infoOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Domain: {result.Domain}");
    Console.WriteLine($"Key Length: {result.KeyLength}");
    Console.WriteLine($"Alt Names: {result.AltNames}");
    Console.WriteLine($"Next Renewal: {result.NextRenewTimeStr}");
    Console.WriteLine($"API Endpoint: {result.ApiEndpoint}");
}

Retrieving Certificate Contents

var getCertOptions = new GetCertificateOptions
{
    Domain = "example.com",
    Ecc = false,
    IncludeKey = true,        // Include private key
    IncludeFullChain = true,  // Include full certificate chain
    IncludeCa = true          // Include CA bundle
};

var result = await client.GetCertificateAsync(getCertOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Certificate: {result.Certificate}");
    Console.WriteLine($"Private Key: {result.PrivateKey}");
    Console.WriteLine($"Full Chain: {result.FullChain}");
    Console.WriteLine($"CA Bundle: {result.CaBundle}");
    
    // Save to files
    await File.WriteAllTextAsync("cert.pem", result.Certificate);
    await File.WriteAllTextAsync("key.pem", result.PrivateKey);
}

Error Handling

All methods return result objects that include:

• IsSuccess: Boolean indicating operation success
• RawOutput: Complete output from acme.sh
• ErrorOutput: Array of error messages (if any)
• Command-specific properties (paths, timestamps, etc.)

var result = await client.IssueAsync(options);

if (!result.IsSuccess)
{
    // Log raw output for debugging
    Console.WriteLine(result.RawOutput);
    
    // Display user-friendly errors
    foreach (var error in result.ErrorOutput)
    {
        Console.WriteLine($"Error: {error}");
    }
}

License

This project is licensed under the MIT License. See the LICENSE file for details.

Türkçe

Açıklama

AcmeshWrapper, popüler acme.sh ACME protokol istemcisi için tip güvenli, asenkron bir .NET sarmalayıcı kütüphanesidir. Let's Encrypt ve diğer ACME uyumlu sertifika otoritelerinden SSL/TLS sertifikalarını almayı, yenilemeyi ve yönetmeyi .NET uygulamalarınızda kolaylaştırır.

Özellikler

• Tip güvenli API: Tüm acme.sh komutları için güçlü tipli seçenekler ve sonuçlar
• Async/await desteği: Tüm işlemler tamamen asenkron
• Kapsamlı komut desteği:
  • list - Tüm sertifikaları listele
  • issue - Yeni sertifika al
  • renew - Belirli sertifikaları yenile
  • renew-all - Yenilenmesi gereken tüm sertifikaları yenile
  • install-cert - Sertifikaları belirli konumlara kur
  • revoke - Sertifikaları iptal et
  • remove - Sertifikaları acme.sh yönetiminden kaldır
  • info - Detaylı sertifika bilgisi al
  • get-certificate - Sertifika dosya içeriklerini getir
• Hata yönetimi: Yapılandırılmış sonuçlarla detaylı hata bilgisi
• Çapraz platform: Windows, Linux ve macOS'ta çalışır
• Minimal bağımlılıklar: Güvenilir süreç yürütme için ProcessX üzerine inşa edilmiştir

Gereksinimler

• .NET Standard 2.1 veya .NET 9.0
• acme.sh kurulu ve PATH'te erişilebilir olmalı
• Sertifika işlemleri için uygun izinler

Kurulum

# NuGet üzerinden kurulum
dotnet add package AcmeshWrapper

# Veya proje referansı ekleyin
dotnet add reference path/to/AcmeshWrapper.csproj

Kullanım Örnekleri

AcmeClient Oluşturma

using AcmeshWrapper;

// Varsayılan yapıcı PATH'ten "acme.sh" kullanır
var client = new AcmeClient();

// Veya özel yol belirtin
var client = new AcmeClient("/usr/local/bin/acme.sh");

Sertifikaları Listeleme

var listOptions = new ListOptions
{
    Raw = true // Ham çıktı formatını al
};

var result = await client.ListAsync(listOptions);

if (result.IsSuccess)
{
    foreach (var cert in result.Certificates)
    {
        Console.WriteLine($"Alan adı: {cert.Domain}");
        Console.WriteLine($"Sonraki yenileme: {cert.Le_Next_Renew_Time}");
        Console.WriteLine($"Anahtar uzunluğu: {cert.Le_Keylength}");
    }
}
else
{
    Console.WriteLine("Sertifikaları listelerken hata:");
    foreach (var error in result.ErrorOutput)
    {
        Console.WriteLine(error);
    }
}

Yeni Sertifika Alma

var issueOptions = new IssueOptions
{
    Domains = new List<string> { "example.com", "www.example.com" },
    WebRoot = "/var/www/html",
    KeyLength = "4096",
    Staging = false // Test için true kullanın
};

var result = await client.IssueAsync(issueOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Sertifika: {result.CertificateFile}");
    Console.WriteLine($"Anahtar: {result.KeyFile}");
    Console.WriteLine($"CA: {result.CaFile}");
    Console.WriteLine($"Tam zincir: {result.FullChainFile}");
}

Sertifika Yenileme

var renewOptions = new RenewOptions
{
    Domain = "example.com",
    Force = false, // Süresi dolmasa bile yenilemeyi zorla
    Ecc = false    // ECC sertifikası kullan
};

var result = await client.RenewAsync(renewOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Yenilenme zamanı: {result.RenewedAt}");
    Console.WriteLine($"Sertifika: {result.CertificatePath}");
}

Sertifika Kurulumu

var installOptions = new InstallCertOptions
{
    Domain = "example.com",
    CertFile = "/etc/nginx/ssl/cert.pem",
    KeyFile = "/etc/nginx/ssl/key.pem",
    FullChainFile = "/etc/nginx/ssl/fullchain.pem",
    ReloadCmd = "systemctl reload nginx"
};

var result = await client.InstallCertAsync(installOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Kurulum zamanı: {result.InstalledAt}");
    Console.WriteLine($"Yenileme komutu çalıştırıldı: {result.ReloadCommandExecuted}");
}

Sertifika İptali

var revokeOptions = new RevokeOptions
{
    Domain = "example.com",
    Reason = RevokeReason.KeyCompromise
};

var result = await client.RevokeAsync(revokeOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"İptal zamanı: {result.RevokedAt}");
    Console.WriteLine($"Parmak izi: {result.CertificateThumbprint}");
}

Tüm Sertifikaları Yenileme

var renewAllOptions = new RenewAllOptions
{
    StopRenewOnError = true // Herhangi bir yenileme başarısız olursa dur
};

var result = await client.RenewAllAsync(renewAllOptions);

Console.WriteLine($"Toplam sertifika: {result.TotalCertificates}");
Console.WriteLine($"Başarılı yenilemeler: {result.SuccessfulRenewals}");
Console.WriteLine($"Atlananlar (süresi dolmamış): {result.SkippedRenewals}");
Console.WriteLine($"Başarısız: {result.FailedRenewals}");

if (result.FailedDomains.Any())
{
    Console.WriteLine("Başarısız alan adları:");
    foreach (var domain in result.FailedDomains)
    {
        Console.WriteLine($"  - {domain}");
    }
}

Sertifika Kaldırma

var removeOptions = new RemoveOptions
{
    Domain = "example.com",
    Ecc = false
};

var result = await client.RemoveAsync(removeOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Kaldırıldı: {result.Domain} - {result.RemovedAt}");
}

Sertifika Bilgisi Alma

var infoOptions = new InfoOptions
{
    Domain = "example.com",
    Ecc = false // ECC sertifikaları için true yapın
};

var result = await client.InfoAsync(infoOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Alan adı: {result.Domain}");
    Console.WriteLine($"Anahtar uzunluğu: {result.KeyLength}");
    Console.WriteLine($"Alternatif isimler: {result.AltNames}");
    Console.WriteLine($"Sonraki yenileme: {result.NextRenewTimeStr}");
    Console.WriteLine($"API endpoint: {result.ApiEndpoint}");
}

Sertifika İçeriğini Alma

var getCertOptions = new GetCertificateOptions
{
    Domain = "example.com",
    Ecc = false,
    IncludeKey = true,        // Özel anahtarı dahil et
    IncludeFullChain = true,  // Tam sertifika zincirini dahil et
    IncludeCa = true          // CA paketini dahil et
};

var result = await client.GetCertificateAsync(getCertOptions);

if (result.IsSuccess)
{
    Console.WriteLine($"Sertifika: {result.Certificate}");
    Console.WriteLine($"Özel anahtar: {result.PrivateKey}");
    Console.WriteLine($"Tam zincir: {result.FullChain}");
    Console.WriteLine($"CA paketi: {result.CaBundle}");
    
    // Dosyalara kaydet
    await File.WriteAllTextAsync("cert.pem", result.Certificate);
    await File.WriteAllTextAsync("key.pem", result.PrivateKey);
}

Hata Yönetimi

Tüm metodlar şunları içeren sonuç nesneleri döndürür:

• IsSuccess: İşlem başarısını gösteren boolean
• RawOutput: acme.sh'tan gelen tam çıktı
• ErrorOutput: Hata mesajları dizisi (varsa)
• Komuta özel özellikler (yollar, zaman damgaları vb.)

var result = await client.IssueAsync(options);

if (!result.IsSuccess)
{
    // Hata ayıklama için ham çıktıyı kaydet
    Console.WriteLine(result.RawOutput);
    
    // Kullanıcı dostu hataları göster
    foreach (var error in result.ErrorOutput)
    {
        Console.WriteLine($"Hata: {error}");
    }
}

Lisans

Bu proje MIT Lisansı altında lisanslanmıştır. Detaylar için LICENSE dosyasına bakın.