FreeBSD Manual Pages
LIBSCEP(1) libscep LIBSCEP(1) NAME libscep - libscep Documentation Contents: NARRATIVE DOCUMENTATION This part of documentation outlines the usage of libscep and describes various topics you might be concerned with such as building, installing and using libscep. Introduction Before you start using this library, we need to go over a few basic concepts for generally using libscep. Paramters & Return Values All libscep functions return an error status of type SCEP_ERROR. You must always check that this value is SCEPE_OK. If it is not, you must not use the return parameters in any way and instead handle the error return by the function and potentially fail gracefully. A typical exam- ple would look like this: SCEP *handle; SCEP_ERROR error = scep_init(&handle); if(error != SCEPE_OK) /* handle error */ /* continue normally */ Output parameters are always passed in last. The above example already shows a good example of that though it has no input parameters. Each function documents on how these paramters are used generally they are only every set in case of success and not touched beforehand. Concept of SCEP The basic library offers functionality to build and decompose SCEP both for client and server. However, the protocol defines some properties that lie beyond building the messages such as the transport to be used. This is not an integral part of the library itself and is left to the individual implementations on how this is achieved. The bindings in Perl, Python or calls from the command line might have different re- quirements and the library does not force any kind of behavior on the user here. Public API Common Parameters Many of the functions share similar parameters which we wish to docu- ment here instead of separately on each function. The variable names in the signature are the same for all concerned functions. SCEP_ERROR scep_message_function() Parameters • handle (SCEP*) -- SCEP handle, see ?? (init...) • sig_cert (X509*) -- Sign PKCS#7 request with this. This will often be the old certificate with which to sign the request for renewal. It is also allowed to use a self-signed certificate here (see ??, selfsigned stuff) • sig_key (EVP_PKEY*) -- Key corresponding to sig_cert. • enc_cert (X509*) -- Certificate with which to encrypt the request. Usually this is the CA/RA certificate for the SCEP server. • pkiMessage (PKCS7**) -- This is an out-parameter: It will be set to a pointer of a PKCS#7 message if the function completes successfully. Otherwise it will be left in its previous state. Returns Error status, see Paramters & Return Values. Return type SCEP_ERROR PKCSReq SCEP_ERROR scep_pkcsreq(SCEP *handle, X509_REQ *req, X509 *sig_cert, EVP_PKEY *sig_key, X509 *enc_cert, PKCS7 **pkiMessage) Create a PKCSReq pkiMessage. See Common Parameters. Special pa- rameters: Parameters • req (X509_REQ*) -- Request for which the PKCSReq mes- sage should be created. CertRep SCEP_ERROR scep_certrep(SCEP *handle, char *transactionID, char *senderNonce, char *pkiStatus, SCEP_FAILINFO failInfo, X509 *requested- Cert, X509 *sig_cert, EVP_PKEY *sig_key, X509 *enc_cert, STACK_OF(X509) *additionalCerts, X509_CRL *crl, PKCS7 **pkiMessage) Parameters • transactionID (char*) -- Transaction ID chosen by the client, needs to be copied over so must stay the same as in the request. • senderNonce (char*) -- Nonce used by sender in original request. • pkiStatus (char*) -- One of FAILURE, SUCCESS or PEND- ING. • failInfo (SCEP_FAILINFO) -- Only makes sense if pkiSta- tus is FAILURE. In that case should represent the cor- rect error according to the standard. • requestedCert (X509*) -- Certificate that was re- quested. Which certificate that is depends on the re- quest, e.g. may be newly issued cert in case of a PKC- SReq. • additionalCerts (STACK_OF(X509) *) -- If you want to add more certificates, to your response, you can use this parameter to add them to the response. The client may ignore them. • crl (X509_CRL*) -- If a CRL was requested instead of a certificate, set this parameter. GetCertInitial SCEP_ERROR scep_get_cert_initial(SCEP *handle, X509_REQ *req, X509 *sig_cert, EVP_PKEY *sig_key, X509 *cacert, X509 *enc_cert, PKCS7 **pkiMessage) Parameters • req (X509_REQ*) -- The request for which this message should be created. It basically needs the subject de- fined here to create the appropriate request to the server. • cacert (X509*) -- Certificate of the CA from which the request expects a new certificate to be issued. This may be the same as enc_cert but can also be different, depending on the PKI setup. GetCert SCEP_ERROR scep_get_cert(SCEP *handle, X509 *sig_cert, EVP_PKEY *sig_key, X509_NAME *issuer, ASN1_INTEGER *serial, X509 *enc_cert, PKCS7 **pkiMessage) Parameters • issuer (X509_NAME*) -- Name of the certificate issuer. • serial (ASN1_INTEGER*) -- Serial number of requested certificate. GetCRL SCEP_ERROR scep_get_crl(SCEP *handle, X509 *sig_cert, EVP_PKEY *sig_key, X509 *req_cert, X509 *enc_cert) Parameters • req_cert (X509*) -- Certificate for which CRL should be requested Unwrapping Unwrapping of requests is done directly with scep_unwrap(), responses should be parsed with the wrapper scep_unwrap_response() as this trans- lates the degenerate PKCS#7 returned by CertRep into their correspond- ing type, i.e. certificate or CRL. SCEP_ERROR scep_unwrap(SCEP *handle, PKCS7 *pkiMessage, X509 *ca_cert, X509 *dec_cert, EVP_PKEY *dec_key, SCEP_DATA **output) Parameters • pkiMessage (PKCS7*) -- Contrary to the creation cases, this unpacks a PKCS#7 message and so this is an input parameter (the message) received from the client. • ca_cert (X509*) -- Root CA certificate used for signa- ture verifcation. • dec_cert (X509*) -- Decryption certificate (either SCEP server or requester certificate). • dec_key (EVP_PKEY*) -- Private key corresponding to dec_cert. • output (SCEP_DATA**) -- Data structure in which all in- formation obtained from parsing should be put. See SCEP_DATA for information on which fields have which meaning. SCEP_ERROR scep_unwrap_response(SCEP *handle, PKCS7 *pkiMessage, X509 *ca_cert, X509 *request_cert, EVP_PKEY *request_key, SCEP_OPERATION re- quest_type, SCEP_DATA **output) This is basically the same as scep_unwrap() but handles extract- ing the correct type of response from the degenerate PKCS#7. Thus, parameters are mostly the same as with scep_unwrap(). Ex- ception: Parameters • request_type (SCEP_OPERATION) -- This indicates the type of request that was made for which this message is a response. This is necessary to interpret the en- crypted content. Engines libscep has support for OpenSSL engines. Because the core functionality is completely independent from any engine support due to the generic PKEY interface, we only provide convenience functions and documenta- tion. OpenSSL offers a high flexibility for using engines, but in 90% of the cases the operations you perform are the same. Thus, the functions of- fered by libscep take this burden from you in these cases. In the re- maining 10% you can use OpenSSL's original support without loss of flexbility or functionality. Configuration There are two types of engines with OpenSSL. First, builtin engines ex- ist that OpenSSL already knows about. Second, an engine called dynamic is able to load engines not already part of OpenSSL during runtime. To ease usage, both ways are supported through a very similar interface. To load a builtin engine you configure libscep like this: scep_conf_set(handle, SCEPCFG_ENGINE, "chil"); This will load the builtin chil engine. On the other hand, a much more common use-case would be to load the engine dynamically: scep_conf_set(handle, SCEPCFG_ENGINE, "dynamic", "pkcs11", "/path/to/engine_pkcs11.so"); This will do several things, but the basic gist is this: If you pass dynamic as the first configuration parameter, two more will be ex- pected: The first denoting the engine ID (while this is your choice, it is generally clear how it should be named). The second parameter then is the path to the acutal shared object. In both cases after calling this the engine will be fully operational if no error has been reported. However, some engines might require ad- ditional variables to be set up to work. In our example above, the PKCS#11 engine requires a MODULE_PATH variable to be set. Thus, it is possible to set any number of variables before loading the engine: scep_conf_set(handle, SCEPCFG_ENGINE_PARAM, "MODULE_PATH", "/path/to/module.so"); Before the engine is actually loaded, the MODULE_PATH variable is set accordingly. To get a list of possible parameters see Getting a List of Supported Parameters for SCEPCFG_ENGINE_PARAM. NOTE: Because these parameters have to be set before the engine is loaded it is not allowed to set parameters after an engine has been loaded (this would be useless anyways). More Flexibility If you require more flexibility, you can create your own engine object to your liking and then just hand it to the library: scep_conf_set(handle, SCEPCFG_ENGINE_OBJ, engine); In this case, libscep will only keep a reference to it but not take ownership of it: You are responsible for cleaning it up. WARNING: If you create multiple handles and mix SCEPCFG_ENGINE_OBJ and SCEPCFG_ENGINE you have to take care of the cleanup order: The global cleanup function ENGINE_cleanup is called if the last engine libscep knows about is freed. But this only applies if this engine was not passed in through SCEPCFG_ENGINE_OBJ. So: Always cleanup in the reverse order you set up and if your explicit engine is the last, you must call ENGINE_cleanup yourself, otherwise you must not. Using the Engine Because of the massive flexibility of the engine API and the diverse usage, we currently do not offer a wrapper around OpenSSL's engine functions. In the most general case, you want to load a private key from your engine: ENGINE *engine = NULL; scep_engine_get(handle, &engine); EVP_PKEY *key = ENGINE_load_private_key(engine, "0:01", NULL, NULL); scep_engine_get gives you a reference to the configured engine. Even if you configured the engine explicitly with SCEPCFG_ENGINE_OBJ you must use this interface for the engine. Afterwards, you can freely use the obtained reference on any OpenSSL engine functions. In the example above, a private key is loaded from our previously con- figured PKCS#11 engine, loading key with ID 0x01 from slot 0. We do not provide the optional callback and data parameters. That's basically it: You now have an EVP_PKEY object usable with the library as OpenSSL is completely transparent regarding these anyway. For engine-specific actions and some additional details, refer to the next section. Special Engines Unfortunately, it often is not that simple because even though there exists a generic interface, technical differences exist. Thus, special handling is required for most engines. Since libscep does not know about these specialties, it is up to the programmer to take control. This is the main reason why we hand out an engine object instead of of- fering wrapping functions. To aid you with this process, we provide documentation for several en- gines. If you have any suggestions, improvements or similar, please let us know and we will add it here. pkcs11_engine With PKCS#11 you are often required to enter a PIN. The engine offers various methods to provide this PIN but the most simple is globally setting it: ENGINE_ctrl_cmd_string(engine, "PIN", "1234", 0); capi The capi engine for Microsoft's CryptoAPI can also be used, but might sometimes need extra parameters. First of all, a store name has to be given. The default name for it is MY but when a new key with CSR is created, it is stored in the REQUEST store: ENGINE_ctrl_cmd_string(engine, "store_name", "REQUEST", 0); Also, if the system store instead of the user's store should be used: ENGINE_ctrl_cmd(engine, "store_flags", 1, NULL, NULL, 0); Tricks Here are a few tricks that might help you in one case or another. Getting a List of Supported Parameters for SCEPCFG_ENGINE_PARAM Whenever you call scep_conf_set with SCEPCFG_ENGINE_PARAM, under the hood, ENGINE_ctrl_cmd_string is called. Thus, any parameter supported by an engine can be set here. For builtin engines, getting a list of these is fairly easy. For example, for CHIL: $ openssl engine chil -vvv (chil) CHIL hardware engine support SO_PATH: Specifies the path to the 'hwcrhk' shared library (input flags): STRING FORK_CHECK: Turns fork() checking on (non-zero) or off (zero) (input flags): NUMERIC THREAD_LOCKING: Turns thread-safe locking on (zero) or off (non-zero) (input flags): NUMERIC Getting this for dynamically loaded engines is a bit more complicated: openssl engine dynamic -pre SO_PATH:path/to/engine_pkcs11.so -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -vvv (dynamic) Dynamic engine loading support [Success]: SO_PATH:/home/javex/tmp/lib/engines/engine_pkcs11.so [Success]: ID:pkcs11 [Success]: LIST_ADD:1 [Success]: LOAD Loaded: (pkcs11) pkcs11 engine SO_PATH: Specifies the path to the 'pkcs11-engine' shared library (input flags): STRING MODULE_PATH: Specifies the path to the pkcs11 module shared library (input flags): STRING PIN: Specifies the pin code (input flags): STRING VERBOSE: Print additional details (input flags): NO_INPUT QUIET: Remove additional details (input flags): NO_INPUT INIT_ARGS: Specifies additional initialization arguments to the pkcs11 module (input flags): STRING NOTE: Currently, we only support string values here. NO_INPUT might also work if you pass NULL as a value but this is untested. API DOCUMENTATION This document describes the API of libscep in detail. If you are look- ing 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 sta- tus. 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 con- juction 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 type type to the value passed as the last argument. The documentation for SCEPCFG_TYPE describes which options are available and which parameters the function expects. All values passed to this function are copied (except if explic- itly stated otherwise), so any memory allocated can be freed af- ter 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 ex- plaining the error code. Example usage: printf("Error message: %s\n", strerror(SCEPE_MEMORY)); Data Types This section lists the data types used within libscep. type 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. type 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. type SCEP_PKISTATUS Prefixed by SCEP_ with possible suffixes SUCCESS, PENDING or FAILURE according to SCEP standard. type SCEP_FAILINFO Enum that represents the failInfo field in a native way. All values are prefixed by SCEP_BAD_. The suffix decides which type of error it is. Available suffixes: ALG, MESSAGE_CHECK, RE- QUEST, TIME, CERT_ID, each corresponding to the failInfo field of an SCEP message. Only relevant if SCEP_PKISTATUS is SCEP_FAILURE. type SCEP_MESSAGE_TYPE Enum that represents all possible messageType fields for SCEP. Prefixed by SCEP_MSG_ and suffixed by one of PKCSREQ, CERTREP, GETCERTINITIAL, GETCERT, GETCRL. The integers in the enum corre- spond to their defined value in the standard, e.g. SCEP_MSG_PKCSREQ has the value 19. type SCEP_DATA Structure with all information contained in an SCEP pkiMessage in a more accessible way. Produced by scep_unwrap() and scep_unwrap_response(). The following field are defined: Param pkiStatus The status of a CertRep message, irrelevant for others Type pkiStatus SCEP_PKISTATUS Param failInfo If pkiStatus is FAILURE, this contains additional infor- mation. Type failInfo SCEP_FAILINFO Param transactionID Transaction ID contained in request. This is always present. Stored hex encoded Type transactionID char * Param senderNonce Always present, exactly 16 byte long. Stored unencoded Type senderNonce unsigned char * Param recipientNonce Only present in CertRep, format like snederNonce Type recipientNonce unsigned char * Param challenge_passowrd Challenge password extracted from a PKCSReq, otherwise unset. Left at generic ASN1_TYPE to make no assumptions about its content, encoding, etc. Type challenge_password ASN1_TYPE * Param signer_certificate The certificate used to sign the message. Currently un- used. Type signer_certificate X509 * Param messageType_str Representation of message type as a stringified integer, e.g. "19" for PKCSReq. Provided for convenience. Type messageType_str char * Param messageType Message type represented by an enum, can assume any valid SCEP messageType. Type messageType SCEP_MESSAGE_TYPE Param request Only set when messageType is PKCSReq, contains the CSR. Type request X509_REQ * Param initialEnrollment Only PKCSReq. Whether this is an initial enrollment mes- sage, determined by whether the request was self-signed. 1 if it is initial enrollment, 0 otherwise. Type initialEnrollment int Param issuer_and_serial Only GetCert and GetCRL. Type issuer_and_serial PKCS7_ISSUER_AND_SERIAL Param issuer_and_subject Only GetCertInitial. Type issuer_and_subject PKCS7_ISSUER_AND_SUBJECT Param certs 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). Type certs STACK_OF(X509) * Param crl Only CertRep if response to GetCRL. Contains requested CRL. Type crl X509_CRL * DEVELOPER DOCUMENTATION Running Tests Running tests is designed to be as easy as possible. However, due to our engine support and the corresponding tests, various dependencies are introduced. Now, the easiest way to get things running is not to care at all. Just go ahead and run this: mkdir build cd build cmake .. make build_test ctest --output-on-failure This should create everything as it is needed without no need for in- tervention. However, this is by far not the quickest way because a lot of libraries have to be built (and if you delete the build directory, they will be built again). Manually Installing Dependencies If you want to have quicker builds, you can manually install the depen- dencies, possibly from your package manager. Here is a list of all the required packages: • libbotan • SoftHSM • libp11 • engine_pkcs11 If you installed everything and their are fairly sane locations, run- ning the code from the previous section should find these. If not, it will probably just build them anyway. It should also find all the cor- rect paths to modules and libraries it requires or will complain if it doesn't. If you have suggestions on how to improve this process, please let us know. • Index • Module Index • Search Page AUTHOR Florian Rchel COPYRIGHT 2013, Florian Rchel 0.1 Nov 01, 2025 LIBSCEP(1)
NAME | NARRATIVE DOCUMENTATION | API DOCUMENTATION | DEVELOPER DOCUMENTATION | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libscep&sektion=1&manpath=FreeBSD+Ports+15.0>