SparrowCert is a simple certificate renewal library for Kestrel-based services. It can be used in any .NET Core-based web service. The service automatically renews certificates, eliminating the need to worry about certificate expiry. It uses the Let's Encrypt ACME protocol to issue and renew certificates and is tested with Kubernetes and Nginx Proxy Manager.
dotnet build to build the projectdotnet run to start the serviceThe service is configured through a cert.json file. Here is an example configuration:
[Note] Of course, your 'cert.json' file SHOULD NOT BE in your repository.
{
"Enabled": true, // default false, discarded if not enabled
"Domains": [
"www.own-domain.org",
"api.own-domain.org" // your domain name (include sub-domains, if you have)
],
"Email": "your@email.address", // your email address for Let's Encrypt account
"RenewBeforeExpiry": "30.00:00:00", // renew 30 days before expiry (default 30 days)
"RenewAfterIssued": "80.00:00:00", // renew 80 days after issued (default null, which means do nothing)
"UseStaging": true, // trying with Let's Encrypt Staging first
"CertSigningRequest": {
"CountryName": "CA", // your country code
"State": "Ontario", // your state
"Locality": "Toronto", // your city
"Organization": "Acme Inc.", // your organization name
"OrganizationUnit": "IT", // your organization unit (department)
"CommonName": "own-domain.org" // your domain name (primary domain)
},
"RenewalFailMode": 1, // 0: unhandled, 1: continue, 2: retry
"KeyAlgorithm": 1, // 0: RSA256, 1: ES256, 2: ES384, 3: ES512
"RenewalStartupDelay": "00:00:00", // delay on startup before renewing
"HttpPort": 5080, // for NAT, customizable HTTP port (80 -> i.e. 5080)
"HttpsPort": 5443, // for NAT, customizable HTTPS port (443 -> i.e. 5443)
"CertFriendlyName": "own-domain.org",
"KeyPath": "/var/sparrow-cert/keys", // where to store the new certificates (typically, with K8s Persistent Volume)
"CertPwd": "your-cert-password", // your certificate password when it is issued (or renewed)
"Notify": {
"Slack": {
"Enabled": true, // default false, discarded if not enabled
"Channels": [ "T0*******HZ" ], // your Slack channel IDs for notification (get it from Slack channel details)
"Token": "<your-slack-token>", // your Slack token, typically starts with 'xoxb-'
"Body": "\n\n\nPlease store the attachment securely, and take the necessary action accordingly.\n\n\n"
},
"Email": {
"Enabled": true, // default false, discarded if not enabled
"SenderName": "cert-bot", // your sender name
"SenderEmail": "<your@email.address>",
"Recipient": "<recipient@email.address>",
"SmtpHost": "<your-smtp-server>",
"SmtpPort": 587, // your SMTP port, typically 587
"SmtpUser": "<your-smtp-user-name>",
"SmtpPwd": "<your-smtp-password>",
"Html": false,
"Body": "\n\n\nPlease store the attachment securely, and take the necessary action accordingly.\n\n\n"
}
}
}
public static void Main(string[] args) {
....
// Load the configuration from the 'cert.json' file
var configPath = "<path to your 'cert.json' file>";
var config = CertJsonConfiguration.FromFile(configPath);
var buildArgs = SparrowCertStartup.SetConfiguration(config);
CreateWebHostBuilder(buildArgs).Build().Run();
}
private static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
WebHost.CreateDefaultBuilder(args)
....
// Use Kestrel with custom configuration
.UseKestrel(o => {
o.ListenAnyIP(args.HttpPort);
o.ListenAnyIP(args.HttpsPort, listenOptions => {
listenOptions.UseHttps(SelfSignedCertGenerator.GenerateCertificate(args.Domain));
});
})
.UseStartup<SparrowCertStartup>(); // Or, add your Startup inherited from SparrowCertStartup
This project is started from reviewing and trying to utilize FluffySpoon.AspNet.EncryptWeMust and Certes, ended-up refactoring quite a bit for my use cases. Kudos to the authors for the initial implementation.
All the credit for pioneering the approach goes to the authors. I just updated the code for my use cases, and hopping this useful to others.