ProvisioningLibrary
Atmel Security Provisioning Library
atcaprov_user_funcs.h File Reference

Function declarations for the user implemented functions of the provisioning library. These functions need to be implemented by the calling application. If a function isn't needed, an empty implementation that returns 0 is required. More...

#include "atcaprov.h"
#include "atcaprov_request.h"

Go to the source code of this file.

Functions

int atcaprov_write_data_zone (void *user_data, const uint8_t config[128])
 User implemented. This is called once by the provisioning process when the data zone is unlocked and gives the user the opportunity to write any data required into the data or OTP zones while they are unlocked. More...
 
void atcaprov_notify (void *user_data, atcaprov_stage_t stage, atcaprov_status_t status)
 User implemented. This is called to notify the calling application of the status of each stage of the provisioning process as started by atcaprov_provision(). More...
 
int atcaprov_certreq_start (void *user_data)
 User implemented. This is called by the provisioning process right before a request for certificates will be sent to the provisioning server using the atcaprov_certreq_send() function. More...
 
int atcaprov_certreq_send (void *user_data, const char *data, size_t data_size)
 User implemented. This is called by the provisioning process to send a request to the provisioning server. This may be called multiple times. More...
 
int atcaprov_certreq_recv (void *user_data, char *data, size_t data_size, size_t *data_recv_size)
 User implemented. This is called by the provisioning process to read a request's reply back from the provisioning server. This may be called multiple times in a row to read back the entire reply. More...
 
int atcaprov_certreq_done (void *user_data)
 User implemented. This is called by the provisioning process to indicate it's done reading the certificate request response using atcaprov_certreq_recv(). More...
 
void atcaprov_request_error (void *user_data, int32_t error_code, const char *error_msg)
 User implemented. This is called if the reply to the certificate request has an error. More...
 

Detailed Description

Function declarations for the user implemented functions of the provisioning library. These functions need to be implemented by the calling application. If a function isn't needed, an empty implementation that returns 0 is required.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The name of Atmel may not be used to endorse or promote products derived from this software without specific prior written permission.
  4. This software may only be redistributed and used in connection with an Atmel integrated circuit.

THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

int atcaprov_certreq_done ( void *  user_data)

User implemented. This is called by the provisioning process to indicate it's done reading the certificate request response using atcaprov_certreq_recv().

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
Returns
0 on success.
int atcaprov_certreq_recv ( void *  user_data,
char *  data,
size_t  data_size,
size_t *  data_recv_size 
)

User implemented. This is called by the provisioning process to read a request's reply back from the provisioning server. This may be called multiple times in a row to read back the entire reply.

The function is allowed to return 0 bytes, indicating no data received yet.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
[out]dataBuffer to put the received data in.
[in]data_sizeMaximum number of bytes to receive.
[out]data_recv_sizeActual number of bytes returned.
Returns
0 on success.
int atcaprov_certreq_send ( void *  user_data,
const char *  data,
size_t  data_size 
)

User implemented. This is called by the provisioning process to send a request to the provisioning server. This may be called multiple times.

Function shouldn't return until all the data has been sent or there was an error.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
[in]dataData to be sent.
[in]data_sizeSize of the data to be sent in bytes.
Returns
0 on success
int atcaprov_certreq_start ( void *  user_data)

User implemented. This is called by the provisioning process right before a request for certificates will be sent to the provisioning server using the atcaprov_certreq_send() function.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
Returns
0 on success
void atcaprov_notify ( void *  user_data,
atcaprov_stage_t  stage,
atcaprov_status_t  status 
)

User implemented. This is called to notify the calling application of the status of each stage of the provisioning process as started by atcaprov_provision().

If a stage completes successfully, this function will be called twice to inform the application when it started (ATCAPROV_STATUS_START) and when it completed (ATCAPROV_STATUS_DONE). If a stage fails, this function will be called twice to inform the application when it started (ATCAPROV_STATUS_START) and when if failed (ATCAPROV_STATUS_ERROR). Finally, if a stage was skipped, this function will only be called once with the ATCAPROV_STATUS_SKIPPED status for that stage.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
[in]stageProvisioning stage the status is about.
[in]statusStatus of the specified provisioning stage.
Returns
0 on success.
void atcaprov_request_error ( void *  user_data,
int32_t  error_code,
const char *  error_msg 
)

User implemented. This is called if the reply to the certificate request has an error.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
[in]error_codeError code return by the provisioning server.
[in]error_msgError message returned by the provisioning server.
int atcaprov_write_data_zone ( void *  user_data,
const uint8_t  config[128] 
)

User implemented. This is called once by the provisioning process when the data zone is unlocked and gives the user the opportunity to write any data required into the data or OTP zones while they are unlocked.

Parameters
[in]user_dataPointer passed into the atcaprov_provision() function by the user.
[in]configDevice's config zone. Provided in case it's useful to the user.
Returns
0 on success