API Documentation¶
This document describes the API of libscep
in detail. If you are looking
for specific functions and implementation details you are correct here. If you
are looking for just using this library, the
narrative documentation might be more for you.
Functions¶
General functions¶
-
SCEP_ERROR
scep_init
(SCEP **handle)¶ Initializes the
SCEP
data structure and returns a success status. The memory for the contained structs is pre-allocated and can later be filled with some data, e.g. configuration values.Make sure to call
scep_cleanup()
when you are done.
-
void
scep_cleanup
(SCEP* handle)¶ Deallocate all memory that was reserved by the client during the process. Afterwards the data that was allocated is no longer accessible. Should be called at the end of the process, in conjuction with calling
scep_init()
at the beginning.Note that there is some data that is not cleaned up. This is data which is documented to not be copied. Take a look at the specific configuration options you are using to avoid memory leaks.
-
SCEP_ERROR
scep_conf_set
(SCEP* handle, SCEPCFG_TYPE type, ...)¶ Set the option for
handle
of typetype
to the value passed as the last argument. The documentation forSCEPCFG_TYPE
describes which options are available and which parameters the function expects.All values passed to this function are copied (except if explicitly stated otherwise), so any memory allocated can be freed after the option has been set. Freeing of the internal memory will be done by
scep_cleanup()
.
Utility functions¶
-
char*
scep_strerror
(SCEP_ERROR err)¶ Turns an internal error code into a human-readable string explaining the error code.
Example usage:
printf("Error message: %s\n", strerror(SCEPE_MEMORY));
Data Types¶
This section lists the data types used within libscep
.
-
SCEP
¶ A handle to a single instance for
libscep
. This needs to be passed to all functions that execute operations. It includes the configuration and some additional information.
-
SCEP_ERROR
¶ An error code indicating a problem. Can be converted into human readable string using
scep_strerror()
.SCEPE_OK
indicates that no error has happened and should be checked after calling any function that returns this type.
-
SCEP_PKISTATUS
¶ Prefixed by
SCEP_
with possible suffixesSUCCESS
,PENDING
orFAILURE
according to SCEP standard.
-
SCEP_FAILINFO
¶ Enum that represents the
failInfo
field in a native way. All values are prefixed bySCEP_BAD_
. The suffix decides which type of error it is. Available suffixes:ALG
,MESSAGE_CHECK
,REQUEST
,TIME
,CERT_ID
, each corresponding to the failInfo field of an SCEP message. Only relevant ifSCEP_PKISTATUS
isSCEP_FAILURE
.
-
SCEP_MESSAGE_TYPE
¶ Enum that represents all possible messageType fields for SCEP. Prefixed by
SCEP_MSG_
and suffixed by one ofPKCSREQ
,CERTREP
,GETCERTINITIAL
,GETCERT
,GETCRL
. The integers in the enum correspond to their defined value in the standard, e.g.SCEP_MSG_PKCSREQ
has the value19
.
-
SCEP_DATA
¶ Structure with all information contained in an SCEP pkiMessage in a more accessible way. Produced by
scep_unwrap()
andscep_unwrap_response()
. The following field are defined:Parameters: - pkiStatus (SCEP_PKISTATUS) – The status of a CertRep message, irrelevant for others
- failInfo (SCEP_FAILINFO) – If
pkiStatus
is FAILURE, this contains additional information. - transactionID (char *) – Transaction ID contained in request. This is always present. Stored hex encoded
- senderNonce (unsigned char *) – Always present, exactly 16 byte long. Stored unencoded
- recipientNonce (unsigned char *) – Only present in CertRep, format like
snederNonce
- challenge_passowrd – Challenge password extracted from a
PKCSReq, otherwise unset. Left at generic
ASN1_TYPE
to make no assumptions about its content, encoding, etc. - signer_certificate (X509 *) – The certificate used to sign the message. Currently unused.
- messageType_str (char *) – Representation of message type as a stringified
integer, e.g.
"19"
for PKCSReq. Provided for convenience. - messageType (SCEP_MESSAGE_TYPE) – Message type represented by an enum, can assume any valid SCEP messageType.
- request (X509_REQ *) – Only set when messageType is PKCSReq, contains the CSR.
- initialEnrollment (int) – Only PKCSReq. Whether this is an initial enrollment message, determined by whether the request was self-signed. 1 if it is initial enrollment, 0 otherwise.
- issuer_and_serial (PKCS7_ISSUER_AND_SERIAL) – Only GetCert and GetCRL.
- issuer_and_subject (PKCS7_ISSUER_AND_SUBJECT) – Only GetCertInitial.
- certs (STACK_OF(X509) *) – Only CertRep if not response to GetCRL. Contains one or more certificate where the first one is the requested certificate (e.g. the newly issued in case of PKCSReq).
- crl (X509_CRL *) – Only CertRep if response to GetCRL. Contains requested CRL.