pt_certificate_api.h File Reference

API for subscribing certificate renewal notications and renewing certificates. More...

#include <stddef.h>
#include <stdbool.h>
#include "pt-client-2/pt_common_api.h"

Go to the source code of this file.

Data Structures
struct	cert_context_s
struct	cert_chain_context_s

Macros
#define	PT_API_VERSION   2
#define	PT_CERTIFICATE_API_H_
#define	CE_STATUS_RANGE_BASE   0x0500
#define	CE_STATUS_RANGE_END   0x0600

Typedefs
typedef struct pt_certificate_list	pt_certificate_list_t
typedef void(*	pt_certificate_renewal_notification_handler) (const connection_id_t connection_id, const char *name, int32_t initiator, int32_t status, const char *description, void *userdata)
	Type definition for certificate renewal notification. This callback will be called to notify the status when a certificate renewal completes. More...
typedef void(*	pt_device_certificate_renew_response_handler) (const connection_id_t connection_id, const char *device_id, const char *name, int32_t status, struct cert_chain_context_s *cert_chain, void *userdata)
	Type definition for certificate renewal notification for device certificate. This callback will be called to notify the status when a certificate renewal completes for device certificate. More...
typedef pt_status_t(*	pt_device_certificate_renew_request_handler) (const connection_id_t connection_id, const char *device_id, const char *name, void *userdata)
	Type definition for certificate renewal request handler for device certificate. This callback will be called when the cloud requests a device certificate to be renewed. More...
typedef void(*	pt_certificates_set_response_handler) (const connection_id_t connection_id, void *userdata)
	Type definition for pt_certificate_renewal_list_set response success and failure handlers. More...
typedef void(*	pt_certificate_renew_response_handler) (const connection_id_t connection_id, void *userdata)
	Type definition for pt_certificate_renew response success and failure handlers.

Enumerations
enum	pt_ce_status_e {   CE_STATUS_SUCCESS = 0, CE_STATUS_ERROR = CE_STATUS_RANGE_BASE, CE_STATUS_INVALID_PARAMETER, CE_STATUS_INSUFFICIENT_BUFFER,   CE_STATUS_OUT_OF_MEMORY, CE_STATUS_ITEM_NOT_FOUND, CE_STATUS_DEVICE_BUSY, CE_STATUS_BAD_INPUT_FROM_SERVER,   CE_STATUS_EST_ERROR, CE_STATUS_STORAGE_ERROR, CE_STATUS_RENEWAL_ITEM_VALIDATION_ERROR, CE_STATUS_BACKUP_ITEM_ERROR,   CE_STATUS_ORIGINAL_ITEM_ERROR, CE_STATUS_RESTORE_BACKUP_ERROR, CE_STATUS_RENEWAL_STATUS_ERROR, CE_STATUS_FORBIDDEN_REQUEST,   CE_STATUS_ITEM_IS_EMPTY, CE_STATUS_NOT_INITIALIZED, CE_STATUS_INIT_FAILED, CE_STATUS_PENDING = 0x5ff,   CE_MAX_STATUS = CE_STATUS_RANGE_END }

Functions
pt_certificate_list_t *	pt_certificate_list_create ()
	Creates a certificate list. More...
void	pt_certificate_list_destroy (pt_certificate_list_t *list)
	Destroys the certificate list. Frees all the certificates added to the list.
pt_status_t	pt_certificate_list_add (pt_certificate_list_t *list, const char *name)
	Adds a certificate to certificate list. More...
pt_status_t	pt_certificate_renewal_list_set (const connection_id_t connection_id, pt_certificate_list_t *list, pt_certificates_set_response_handler success_handler, pt_certificates_set_response_handler failure_handler, void *userdata)
	Sends the certificate list to Edge, triggering renewal subscriptions of the certificates in the list. More...
pt_status_t	pt_certificate_renew (const connection_id_t connection_id, const char *name, pt_certificate_renew_response_handler success_handler, pt_certificate_renew_response_handler failure_handler, void *userdata)
	Requests the renewal of the certificate specified by the name parameter. More...
pt_status_t	pt_device_certificate_renew (const connection_id_t connection_id, const char *device_id, const char *name, const char *csr, const size_t csr_length, pt_device_certificate_renew_response_handler success_handler, pt_device_certificate_renew_response_handler failure_handler, void *userdata)
	Requests the renewal of the certificate specified by the name parameter using the certificate signing request specified by the csr parameter. More...
pt_status_t	pt_device_certificate_renew_request_finish (const connection_id_t connection_id, const char *device_id, const pt_ce_status_e status)
	Finish device certificate renewal request. More...
void	pt_free_certificate_chain_context (struct cert_chain_context_s *context)
	Free a cert_chain_context_s structure passed to the certificate renewal notification callback.. More...

Detailed Description

API for subscribing certificate renewal notications and renewing certificates.

To be able to renew a certificate:

1. The certificate renewal notification handler needs to be set correctly using pt_client_create.
2. The certificate needs to be added (pt_certificate_list_add) to certificate list that was created using pt_certificate_list_create.
3. The certification list needs to be send to Edge using pt_certificate_renewal_list_set.
4. The pt_certificate_renew must be called for the certificates that were added to the list.

After setting notification callback and subscribing to certificate renewals, the client must also be prepared to receive certificate renewal notification callback also for cloud initiated certificate renewal.