Funzione CertStore_InstallClientCertificateCertStore_InstallClientCertificate function

Intestazione: #include <applibs/certstore.h>Header: #include <applibs/certstore.h>

Installa un certificato client costituito da un certificato pubblico e da una chiave privata con un ID specificato.Installs a client certificate that consists of a public certificate and a private key with the specified ID. È quindi possibile usare l'ID per fare riferimento al certificato in altre funzioni.The ID can then be used to refer to the certificate in other functions. Se è già installato un qualsiasi tipo di certificato con lo stesso ID, verrà sostituito con il nuovo certificato.If any type of certificate is already installed with the same ID, it will be replaced with the new certificate.

int CertStore_InstallClientCertificate(const char *identifier, const char *certBlob, size_t certBlobLength, const char *privateKeyBlob, size_t privateKeyBlobLength, const char *privateKeyPassword);

ParametriParameters

  • identifier ID del certificato.identifier The ID of the certificate.

  • certBlob Puntatore a un BLOB che contiene il certificato pubblico in formato PEM.certBlob A pointer to a blob that contains the public certificate in PEM format. Il BLOB deve contenere solo il contenuto compreso tra i tag -----BEGIN... e -----END....The blob must only contain the content between the -----BEGIN... and -----END... tags. I tag per un certificato, ad esempio, sono -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----.For example, the tags for a certificate are -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  • certBlobLength Lunghezza del BLOB del certificato, escluso il carattere di terminazione Null.certBlobLength The length of the certificate blob, not including the null-terminator character.

  • privateKeyBlob Puntatore a un BLOB che contiene la chiave privata in formato PEM.privateKeyBlob A pointer to a blob that contains the private key in PEM format.

  • privateKeyBlobLength Lunghezza del BLOB del certificato, escluso il carattere di terminazione Null.privateKeyBlobLength The length of the certificate blob, not including the null-terminator character.

  • privateKeyPassword Puntatore a una matrice di caratteri con terminazione NULL che contiene la password della chiave privata.privateKeyPassword A pointer to a null-terminated character array that contains the private key password. La lunghezza della matrice deve essere minore o uguale al numero di byte definito per CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH.The length of the array must be less than or equal to CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH bytes. Se il valore di privateKeyBlob è crittografato, è necessaria una password.A password is required if privateKeyBlob is encrypted.

ErroriErrors

Restituisce-1 se viene rilevato un errore e imposta sul errno valore di errore.Returns -1 if an error is encountered and sets errno to the error value.

  • EACCES: l'operazione non è consentita perché la funzionalità CertStore non è impostata nel manifesto dell'applicazione.EACCES: the operation isn't allowed because either the CertStore capability isn't set in the application manifest.

  • EAGAIN: il componente certstore del sistema operativo non è ancora pronto.EAGAIN: the OS certstore component isn't ready yet.

  • EFAULT: il parametro certBlob, identifier o privateKeyBlob è NULL.EFAULT: the certBlob, identifier, or privateKeyBlob parameter is NULL.

  • EINVAL: il parametro identifier non ha terminazione NULL oppure certBlob o privateKeyBlob include dati non validi.EINVAL: the identifier parameter isn't NULL-terminated, the certBlob or privateKeyBlob includes invalid data.

  • ENOSPC: lo spazio nell'archivio certificati non è sufficiente per il certificato.ENOSPC: there is not enough space in the certificate storage for this certificate.

  • ERANGE: il valore di certBlobLength o privateKeyBlobLength è zero oppure maggiore di quello definito per CERTSTORE_MAX_CERT_SIZE oppure la lunghezza impostata per privateKeyPassword è maggiore di quella definita per CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH.ERANGE: the certBlobLength or privateKeyBlobLength is zero or greater than CERTSTORE_MAX_CERT_SIZE or the privateKeyPassword length is greater than CERTSTORE_MAX_PRIVATE_KEY_PASSWORD_LENGTH.

È errno possibile specificare anche qualsiasi altro tipo di errore. tali errori non sono deterministici e non vi è alcuna garanzia che lo stesso comportamento venga mantenuto tramite gli aggiornamenti del sistema.Any other errno may also be specified; such errors aren't deterministic and there's no guarantee that the same behavior will be retained through system updates.

Valore restituitoReturn value

Restituisce 0 per l'esito positivo o-1 per l'esito negativo, nel qual caso errno viene impostato sul valore di errore.Returns 0 for success, or -1 for failure, in which case errno is set to the error value.

OsservazioniRemarks

Un identificatore valido deve essere una stringa univoca la cui lunghezza è compresa tra uno e il numero di caratteri di CERTSTORE_MAX_IDENTIFIER_LENGTH.A valid identifier must be a unique string from one to CERTSTORE_MAX_IDENTIFIER_LENGTH characters in length. In un identificatore è possibile usare i caratteri seguenti:The following characters are valid in an identifer:

  • Dalla 'A' alla 'Z''A' to 'Z'
  • Dalla 'a' alla 'z''a' to 'z'
  • Da '0' a '9''0' to '9'
  • '.', '-' o '''.' or '-' or ''

Attenzione

Poiché gli ID certificato sono a livello di sistema, un comando azsphere o una chiamata di funzione che aggiunge un nuovo certificato può sovrascrivere un certificato aggiunto da un comando o una chiamata di funzione precedente, generando possibilmente errori di connessione di rete.Because certificate IDs are system-wide, an azsphere command or a function call that adds a new certificate can overwrite a certificate that was added by an earlier command or function call, potentially causing network connection failures. È consigliabile sviluppare procedure ben definite per l'aggiornamento dei certificati e scegliere con attenzione gli ID certificato.We strongly recommend that you develop clear certificate update procedures and choose certificate IDs carefully.

Per altre informazioni sul modo in cui Azure Sphere usa gli ID certificato, vedere ID certificato.See Certificate IDs for more information about how Azure Sphere uses certificate IDs.

Requisiti del manifesto dell'applicazioneApplication manifest requirements

Il manifesto dell'applicazione deve includere la funzionalità CertStore.The application manifest must include the CertStore capability.