ACME client (Automatic Certificate Management Environment) More...

#include "acme/acme_client.h"
#include "acme/acme_client_directory.h"
#include "acme/acme_client_nonce.h"
#include "acme/acme_client_account.h"
#include "acme/acme_client_order.h"
#include "acme/acme_client_auth.h"
#include "acme/acme_client_challenge.h"
#include "acme/acme_client_certificate.h"
#include "acme/acme_client_misc.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL ACME_TRACE_LEVEL

Functions
error_t	acmeClientInit (AcmeClientContext *context)
	Initialize ACME client context. More...

error_t	acmeClientRegisterTlsInitCallback (AcmeClientContext *context, AcmeClientTlsInitCallback callback)
	Register TLS initialization callback function. More...

error_t	acmeClientRegisterCsrCallback (AcmeClientContext *context, AcmeClientCsrCallback callback)
	Register CSR generation callback function. More...

error_t	acmeClientSetPrng (AcmeClientContext context, const PrngAlgo prngAlgo, void *prngContext)
	Set the pseudo-random number generator to be used. More...

error_t	acmeClientSetTimeout (AcmeClientContext *context, systime_t timeout)
	Set communication timeout. More...

error_t	acmeClientSetHost (AcmeClientContext context, const char_t host)
	Set the domain name of the ACME server. More...

error_t	acmeClientSetDirectoryUri (AcmeClientContext context, const char_t directoryUri)
	Set the URI of the directory object. More...

error_t	acmeClientBindToInterface (AcmeClientContext context, NetInterface interface)
	Bind the ACME client to a particular network interface. More...

error_t	acmeClientConnect (AcmeClientContext context, const IpAddr serverIpAddr, uint16_t serverPort)
	Establish a connection with the specified ACME server. More...

error_t	acmeClientSetAccountKey (AcmeClientContext context, const char_t publicKey, size_t publicKeyLen, const char_t privateKey, size_t privateKeyLen, const char_t password)
	Load account key pair. More...

error_t	acmeClientCreateAccount (AcmeClientContext context, const AcmeAccountParams params)
	Account creation. More...

error_t	acmeClientUpdateAccount (AcmeClientContext context, const AcmeAccountParams params)
	Account information update. More...

error_t	acmeClientChangeAccountKey (AcmeClientContext context, const char_t publicKey, size_t publicKeyLen, const char_t privateKey, size_t privateKeyLen, const char_t password)
	Account key rollover. More...

error_t	acmeClientDeactivateAccount (AcmeClientContext *context)
	ACME account deactivation. More...

error_t	acmeClientCreateOrder (AcmeClientContext context, const AcmeOrderParams params)
	Begin the certificate issuance process. More...

const char_t *	acmeClientGetHttpKeyAuthorization (AcmeClientContext context, const char_t token)
	Get the key authorization that matches a given token (HTTP challenge) More...

const char_t *	acmeClientGetDnsKeyAuthorization (AcmeClientContext context, const char_t identifier)
	Get the key authorization digest that matches a given identifier (DNS challenge) More...

const char_t *	acmeClientGetTlsAlpnCertificate (AcmeClientContext context, const char_t identifier)
	Get the self-certificate that matches a given identifier (TLS-ALPN challenge) More...

error_t	acmeClientPollOrderStatus (AcmeClientContext context, AcmeOrderStatus orderStatus)
	Poll for order status. More...

error_t	acmeClientDownloadCertificate (AcmeClientContext context, char_t buffer, size_t size, size_t *length)
	Download the certificate. More...

error_t	acmeClientRevokeCertificate (AcmeClientContext context, const char_t cert, size_t certLen, const char_t privateKey, size_t privateKeyLen, const char_t password, AcmeReasonCode reason)
	Certificate revocation. More...

error_t	acmeClientDisconnect (AcmeClientContext *context)
	Gracefully disconnect from the ACME server. More...

error_t	acmeClientClose (AcmeClientContext *context)
	Close the connection with the ACME server. More...

void	acmeClientDeinit (AcmeClientContext *context)
	Release ACME client context. More...

Detailed Description

ACME client (Automatic Certificate Management Environment)

License

SPDX-License-Identifier: GPL-2.0-or-later

This file is part of CycloneACME Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Description

ACME is a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. Refer to the following RFCs for complete details:

RFC 8555: Automatic Certificate Management Environment (ACME)
RFC 8737: ACME TLS Application-Layer Protocol Negotiation (ALPN) Challenge Extension
RFC 7515: JSON Web Signature (JWS)
RFC 7517: JSON Web Key (JWK)
RFC 7518: JSON Web Algorithms (JWA)
RFC 7638: JSON Web Key (JWK) Thumbprint

Author: Oryx Embedded SARL (www.oryx-embedded.com)

Version: 2.5.0

Definition in file acme_client.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL ACME_TRACE_LEVEL

Definition at line 45 of file acme_client.c.

Function Documentation

◆ acmeClientBindToInterface()

error_t acmeClientBindToInterface	(	AcmeClientContext *	context,
		NetInterface *	interface
	)

Bind the ACME client to a particular network interface.

Parameters

[in]	context	Pointer to the ACME client context
[in]	interface	Network interface to be used

Returns: Error code

Definition at line 249 of file acme_client.c.

◆ acmeClientChangeAccountKey()

error_t acmeClientChangeAccountKey	(	AcmeClientContext *	context,
		const char_t *	publicKey,
		size_t	publicKeyLen,
		const char_t *	privateKey,
		size_t	privateKeyLen,
		const char_t *	password
	)

Account key rollover.

Parameters

[in]	context	Pointer to the ACME client context
[in]	publicKey	New public key (PEM format)
[in]	publicKeyLen	Length of the new public key
[in]	privateKey	New private key (PEM format)
[in]	privateKeyLen	Length of the new private key
[in]	password	NULL-terminated string containing the password. This parameter is required if the private key is encrypted

Returns: Error code

Definition at line 656 of file acme_client.c.

◆ acmeClientClose()

error_t acmeClientClose ( AcmeClientContext * context )

Close the connection with the ACME server.

Parameters

[in] context Pointer to the ACME client context

Returns: Error code

Definition at line 1771 of file acme_client.c.

◆ acmeClientConnect()

error_t acmeClientConnect	(	AcmeClientContext *	context,
		const IpAddr *	serverIpAddr,
		uint16_t	serverPort
	)

Establish a connection with the specified ACME server.

Parameters

[in]	context	Pointer to the ACME client context
[in]	serverIpAddr	IP address of the ACME server to connect to
[in]	serverPort	Port number

Returns: Error code

Definition at line 272 of file acme_client.c.

◆ acmeClientCreateAccount()

error_t acmeClientCreateAccount	(	AcmeClientContext *	context,
		const AcmeAccountParams *	params
	)

Account creation.

Parameters

[in]	context	Pointer to the ACME client context
[in]	params	Account information

Returns: Error code

Definition at line 426 of file acme_client.c.

◆ acmeClientCreateOrder()

error_t acmeClientCreateOrder	(	AcmeClientContext *	context,
		const AcmeOrderParams *	params
	)

Begin the certificate issuance process.

Parameters

[in]	context	Pointer to the ACME client context
[in]	params	Certificate order information

Returns: Error code

Definition at line 885 of file acme_client.c.

◆ acmeClientDeactivateAccount()

error_t acmeClientDeactivateAccount ( AcmeClientContext * context )

ACME account deactivation.

Parameters

[in] context Pointer to the ACME client context

Returns: Error code

Definition at line 773 of file acme_client.c.

◆ acmeClientDeinit()

void acmeClientDeinit ( AcmeClientContext * context )

Release ACME client context.

Parameters

[in] context Pointer to the ACME client context

Definition at line 1792 of file acme_client.c.

◆ acmeClientDisconnect()

error_t acmeClientDisconnect ( AcmeClientContext * context )

Gracefully disconnect from the ACME server.

Parameters

[in] context Pointer to the ACME client context

Returns: Error code

Definition at line 1705 of file acme_client.c.

◆ acmeClientDownloadCertificate()

error_t acmeClientDownloadCertificate	(	AcmeClientContext *	context,
		char_t *	buffer,
		size_t	size,
		size_t *	length
	)

Download the certificate.

Parameters

[in]	context	Pointer to the ACME client context
[out]	buffer	Pointer to the buffer where to store the certificate chain
[in]	size	Size of the buffer, in bytes
[out]	length	Actual length of the certificate chain, in bytes

Returns: Error code

Definition at line 1458 of file acme_client.c.

◆ acmeClientGetDnsKeyAuthorization()

const char_t* acmeClientGetDnsKeyAuthorization	(	AcmeClientContext *	context,
		const char_t *	identifier
	)

Get the key authorization digest that matches a given identifier (DNS challenge)

Parameters

[in]	context	Pointer to the ACME client context
[in]	identifier	NULL-terminated string that contains the domain name

Returns: The function returns a NULL-terminated string that contains the Base64url-encoded digest of the key authorization if the identifier is valid. Else, the NULL pointer is returned

Definition at line 1088 of file acme_client.c.

◆ acmeClientGetHttpKeyAuthorization()

const char_t* acmeClientGetHttpKeyAuthorization	(	AcmeClientContext *	context,
		const char_t *	token
	)

Get the key authorization that matches a given token (HTTP challenge)

Parameters

[in]	context	Pointer to the ACME client context
[in]	token	NULL-terminated string that contains the token

Returns: The function returns a NULL-terminated string that contains the key authorization if the token is valid. Else, the NULL pointer is returned

Definition at line 1037 of file acme_client.c.

◆ acmeClientGetTlsAlpnCertificate()

const char_t* acmeClientGetTlsAlpnCertificate	(	AcmeClientContext *	context,
		const char_t *	identifier
	)

Get the self-certificate that matches a given identifier (TLS-ALPN challenge)

Parameters

[in]	context	Pointer to the ACME client context
[in]	identifier	NULL-terminated string that contains the domain name

Returns: The function returns a NULL-terminated string that contains the TLS-ALPN certificate if the identifier is valid. Else, the NULL pointer is returned

Definition at line 1157 of file acme_client.c.

◆ acmeClientInit()

error_t acmeClientInit ( AcmeClientContext * context )

Initialize ACME client context.

Parameters

[in] context Pointer to the ACME client context

Returns: Error code

Definition at line 69 of file acme_client.c.

◆ acmeClientPollOrderStatus()

error_t acmeClientPollOrderStatus	(	AcmeClientContext *	context,
		AcmeOrderStatus *	orderStatus
	)

Poll for order status.

Parameters

[in]	context	Pointer to the ACME client context
[out]	orderStatus	Order status

Returns: Error code

Definition at line 1206 of file acme_client.c.

◆ acmeClientRegisterCsrCallback()

error_t acmeClientRegisterCsrCallback	(	AcmeClientContext *	context,
		AcmeClientCsrCallback	callback
	)

Register CSR generation callback function.

Parameters

[in]	context	Pointer to the ACME client context
[in]	callback	TLS initialization callback function

Returns: Error code

Definition at line 130 of file acme_client.c.

◆ acmeClientRegisterTlsInitCallback()

error_t acmeClientRegisterTlsInitCallback	(	AcmeClientContext *	context,
		AcmeClientTlsInitCallback	callback
	)

Register TLS initialization callback function.

Parameters

[in]	context	Pointer to the ACME client context
[in]	callback	TLS initialization callback function

Returns: Error code

Definition at line 108 of file acme_client.c.

◆ acmeClientRevokeCertificate()

error_t acmeClientRevokeCertificate	(	AcmeClientContext *	context,
		const char_t *	cert,
		size_t	certLen,
		const char_t *	privateKey,
		size_t	privateKeyLen,
		const char_t *	password,
		AcmeReasonCode	reason
	)

Certificate revocation.

Parameters

[in]	context	Pointer to the ACME client context
[in]	cert	Certificate to be revoked (PEM format)
[in]	certLen	Length of the certificate, in bytes
[in]	privateKey	Private key associated with the certificate (PEM format). This parameter is required if the certificate key, rather than the account key, is to be used to sign the revocation request
[in]	privateKeyLen	Length of the private key
[in]	password	NULL-terminated string containing the password. This parameter is required if the private key is encrypted
[in]	reason	Revocation reason code

Returns: Error code

Definition at line 1582 of file acme_client.c.

◆ acmeClientSetAccountKey()

error_t acmeClientSetAccountKey	(	AcmeClientContext *	context,
		const char_t *	publicKey,
		size_t	publicKeyLen,
		const char_t *	privateKey,
		size_t	privateKeyLen,
		const char_t *	password
	)

Load account key pair.

Parameters

[in]	context	Pointer to the ACME client context
[in]	publicKey	Public key (PEM format)
[in]	publicKeyLen	Length of the public key
[in]	privateKey	Private key (PEM format)
[in]	privateKeyLen	Length of the private key
[in]	password	NULL-terminated string containing the password. This parameter is required if the private key is encrypted

Returns: Error code

Definition at line 399 of file acme_client.c.

◆ acmeClientSetDirectoryUri()

error_t acmeClientSetDirectoryUri	(	AcmeClientContext *	context,
		const char_t *	directoryUri
	)

Set the URI of the directory object.

Parameters

[in]	context	Pointer to the ACME client context
[in]	directoryUri	NULL-terminated string containing the directory URI

Returns: Error code

Definition at line 223 of file acme_client.c.

◆ acmeClientSetHost()

error_t acmeClientSetHost	(	AcmeClientContext *	context,
		const char_t *	host
	)

Set the domain name of the ACME server.

Parameters

[in]	context	Pointer to the ACME client context
[in]	host	NULL-terminated string containing the host name

Returns: Error code

Definition at line 198 of file acme_client.c.

◆ acmeClientSetPrng()

error_t acmeClientSetPrng	(	AcmeClientContext *	context,
		const PrngAlgo *	prngAlgo,
		void *	prngContext
	)

Set the pseudo-random number generator to be used.

Parameters

[in]	context	Pointer to the ACME client context
[in]	prngAlgo	PRNG algorithm
[in]	prngContext	Pointer to the PRNG context

Returns: Error code

Definition at line 153 of file acme_client.c.

◆ acmeClientSetTimeout()

error_t acmeClientSetTimeout	(	AcmeClientContext *	context,
		systime_t	timeout
	)

Set communication timeout.

Parameters

[in]	context	Pointer to the ACME client context
[in]	timeout	Timeout value, in milliseconds

Returns: Error code

Definition at line 177 of file acme_client.c.

◆ acmeClientUpdateAccount()

error_t acmeClientUpdateAccount	(	AcmeClientContext *	context,
		const AcmeAccountParams *	params
	)

Account information update.

Parameters

[in]	context	Pointer to the ACME client context
[in]	params	Updated account information

Returns: Error code

Definition at line 538 of file acme_client.c.

Macros

Functions

Detailed Description

License

Description

Macro Definition Documentation

◆ TRACE_LEVEL

Function Documentation

◆ acmeClientBindToInterface()

◆ acmeClientChangeAccountKey()

◆ acmeClientClose()

◆ acmeClientConnect()

◆ acmeClientCreateAccount()

◆ acmeClientCreateOrder()

◆ acmeClientDeactivateAccount()

◆ acmeClientDeinit()

◆ acmeClientDisconnect()

◆ acmeClientDownloadCertificate()

◆ acmeClientGetDnsKeyAuthorization()

◆ acmeClientGetHttpKeyAuthorization()

◆ acmeClientGetTlsAlpnCertificate()

◆ acmeClientInit()

◆ acmeClientPollOrderStatus()

◆ acmeClientRegisterCsrCallback()

◆ acmeClientRegisterTlsInitCallback()

◆ acmeClientRevokeCertificate()

◆ acmeClientSetAccountKey()

◆ acmeClientSetDirectoryUri()

◆ acmeClientSetHost()

◆ acmeClientSetPrng()

◆ acmeClientSetTimeout()

◆ acmeClientUpdateAccount()