ASN.1

Functions
int	wc_InitCert (Cert *)
	This function initializes a default cert, with the default options: version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank, daysValid = 500, selfSigned = 1 (true) use subject as issuer, subject = blank. More...
Cert *	wc_CertNew (void *heap)
	This function allocates a new Cert structure for use during cert operations without the application having to allocate the structure itself. The Cert structure is also initialized by this function thus removing the need to call wc_InitCert(). When the application is finished using the allocated Cert structure wc_CertFree() must be called. More...
void	wc_CertFree (Cert *cert)
	This function frees the memory allocated for a cert structure by a previous call to wc_CertNew(). More...
int	wc_MakeCert (Cert *cert, byte *derBuffer, word32 derSz, RsaKey *rsaKey, ecc_key *eccKey, WC_RNG *rng)
	Used to make CA signed certs. Called after the subject information has been entered. This function makes an x509 Certificate v3 RSA or ECC from a cert input. It then writes this cert to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called. More...
int	wc_MakeCertReq (Cert *cert, byte *derBuffer, word32 derSz, RsaKey *rsaKey, ecc_key *eccKey)
	This function makes a certificate signing request using the input certificate and writes the output to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate request. wc_SignCert() will need to be called after this function to sign the certificate request. Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an example usage of this function. More...
int	wc_SignCert (int requestSz, int sigType, byte *derBuffer, word32 derSz, RsaKey *rsaKey, ecc_key *eccKey, WC_RNG *rng)
	This function signs buffer and adds the signature to the end of buffer. It takes in a signature type. Must be called after wc_MakeCert() or wc_MakeCertReq() if creating a CA signed cert. More...
int	wc_MakeSelfCert (Cert *cert, byte *derBuffer, word32 derSz, RsaKey *key, WC_RNG *rng)
	This function is a combination of the previous two functions, wc_MakeCert and wc_SignCert for self signing (the previous functions may be used for CA requests). It makes a certificate, and then signs it, generating a self-signed certificate. More...
int	wc_SetIssuer (Cert *cert, const char *issuerFile)
	This function sets the issuer for a certificate to the issuer in the provided pem issuerFile. It also changes the certificate’s self-signed attribute to false. The issuer specified in issuerFile is verified prior to setting the cert issuer. This method is used to set fields prior to signing. More...
int	wc_SetSubject (Cert *cert, const char *subjectFile)
	This function sets the subject for a certificate to the subject in the provided pem subjectFile. This method is used to set fields prior to signing. More...
int	wc_SetSubjectRaw (Cert *cert, const byte *der, int derSz)
	This function sets the raw subject for a certificate from the subject in the provided der buffer. This method is used to set the raw subject field prior to signing. More...
int	wc_GetSubjectRaw (byte **subjectRaw, Cert *cert)
	This function gets the raw subject from the certificate structure. More...
int	wc_SetAltNames (Cert *cert, const char *file)
	This function sets the alternate names for a certificate to the alternate names in the provided pem file. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing. More...
int	wc_SetIssuerBuffer (Cert *cert, const byte *der, int derSz)
	This function sets the issuer for a certificate from the issuer in the provided der buffer. It also changes the certificate’s self-signed attribute to false. This method is used to set fields prior to signing. More...
int	wc_SetIssuerRaw (Cert *cert, const byte *der, int derSz)
	This function sets the raw issuer for a certificate from the issuer in the provided der buffer. This method is used to set the raw issuer field prior to signing. More...
int	wc_SetSubjectBuffer (Cert *cert, const byte *der, int derSz)
	This function sets the subject for a certificate from the subject in the provided der buffer. This method is used to set fields prior to signing. More...
int	wc_SetAltNamesBuffer (Cert *cert, const byte *der, int derSz)
	This function sets the alternate names for a certificate from the alternate names in the provided der buffer. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing. More...
int	wc_SetDatesBuffer (Cert *cert, const byte *der, int derSz)
	This function sets the dates for a certificate from the date range in the provided der buffer. This method is used to set fields prior to signing. More...
int	wc_SetAuthKeyIdFromPublicKey (Cert *cert, RsaKey *rsakey, ecc_key *eckey)
	Set AKID from either an RSA or ECC public key. note: Only set one of rsakey or eckey, not both. More...
int	wc_SetAuthKeyIdFromCert (Cert *cert, const byte *der, int derSz)
	Set AKID from from DER encoded certificate. More...
int	wc_SetAuthKeyId (Cert *cert, const char *file)
	Set AKID from certificate file in PEM format. More...
int	wc_SetSubjectKeyIdFromPublicKey (Cert *cert, RsaKey *rsakey, ecc_key *eckey)
	Set SKID from RSA or ECC public key. More...
int	wc_SetSubjectKeyId (Cert *cert, const char *file)
	Set SKID from public key file in PEM format. Both arguments are required. More...
int	wc_PemPubKeyToDer (const char *fileName, unsigned char *derBuf, int derSz)
	Loads a PEM key from a file and converts to a DER encoded buffer. More...
int	wc_PubKeyPemToDer (const unsigned char *pem, int pemSz, unsigned char *buff, int buffSz)
	Convert a PEM encoded public key to DER. Returns the number of bytes written to the buffer or a negative value for an error. More...
int	wc_PemCertToDer (const char *fileName, unsigned char *derBuf, int derSz)
	This function converts a pem certificate to a der certificate, and places the resulting certificate in the derBuf buffer provided. More...
int	wc_DerToPem (const byte *der, word32 derSz, byte *output, word32 outputSz, int type)
	This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output. More...
int	wc_DerToPemEx (const byte *der, word32 derSz, byte *output, word32 outputSz, byte *cipherIno, int type)
	This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output. Allows setting cipher info. More...
int	wc_EccPrivateKeyDecode (const byte *input, word32 *inOutIdx, ecc_key *key, word32 inSz)
	This function reads in an ECC private key from the input buffer, input, parses the private key, and uses it to generate an ecc_key object, which it stores in key. More...
int	wc_EccKeyToDer (ecc_key *key, byte *output, word32 inLen)
	This function writes a private ECC key to der format. More...
int	wc_EccPublicKeyDecode (const byte *input, word32 *inOutIdx, ecc_key *key, word32 inSz)
	Decodes an ECC public key from an input buffer. It will parse an ASN sequence to retrieve the ECC key. More...
int	wc_EccPublicKeyToDer (ecc_key *key, byte *output, word32 inLen, int with_AlgCurve)
	This function converts the ECC public key to DER format. It returns the size of buffer used. The public ECC key in DER format is stored in output buffer. The with_AlgCurve flag will include a header that has the Algorithm and Curve information. More...
int	wc_EccPublicKeyToDer_ex (ecc_key *key, byte *output, word32 inLen, int with_AlgCurve, int comp)
	This function converts the ECC public key to DER format. It returns the size of buffer used. The public ECC key in DER format is stored in output buffer. The with_AlgCurve flag will include a header that has the Algorithm and Curve information. The comp parameter determines if the public key will be exported as compressed. More...
int	wc_Curve25519PrivateKeyDecode (const byte *input, word32 *inOutIdx, curve25519_key *key, word32 inSz)
	This function decodes a Curve25519 private key (only) from a DER encoded buffer. More...
int	wc_Curve25519PublicKeyDecode (const byte *input, word32 *inOutIdx, curve25519_key *key, word32 inSz)
	This function decodes a Curve25519 public key (only) from a DER encoded buffer. More...
int	wc_Curve25519KeyDecode (const byte *input, word32 *inOutIdx, curve25519_key *key, word32 inSz)
	This function decodes a Curve25519 key from a DER encoded buffer. It can decode either a private key, a public key, or both. More...
int	wc_Curve25519PrivateKeyToDer (curve25519_key *key, byte *output, word32 inLen)
	This function encodes a Curve25519 private key to DER format. If the input key structure contains a public key, it will be ignored. More...
int	wc_Curve25519PublicKeyToDer (curve25519_key *key, byte *output, word32 inLen, int withAlg)
	This function encodes a Curve25519 public key to DER format. If the input key structure contains a private key, it will be ignored. More...
int	wc_Curve25519KeyToDer (curve25519_key *key, byte *output, word32 inLen, int withAlg)
	This function encodes a Curve25519 key to DER format. It can encode either a private key, a public key, or both. More...
word32	wc_EncodeSignature (byte *out, const byte *digest, word32 digSz, int hashOID)
	This function encodes a digital signature into the output buffer, and returns the size of the encoded signature created. More...
int	wc_GetCTC_HashOID (int type)
	This function returns the hash OID that corresponds to a hashing type. For example, when given the type: WC_SHA512, this function returns the identifier corresponding to a SHA512 hash, SHA512h. More...
void	wc_SetCert_Free (Cert *cert)
	This function cleans up memory and resources used by the certificate structure's decoded cert cache. When WOLFSSL_CERT_GEN_CACHE is defined the decoded cert structure is cached in the certificate structure. This allows subsequent calls to certificate set functions to avoid parsing the decoded cert on each call. More...
int	wc_GetPkcs8TraditionalOffset (byte *input, word32 *inOutIdx, word32 sz)
	This function finds the beginning of the traditional private key inside a PKCS#8 unencrypted buffer. More...
int	wc_CreatePKCS8Key (byte *out, word32 *outSz, byte *key, word32 keySz, int algoID, const byte *curveOID, word32 oidSz)
	This function takes in a DER private key and converts it to PKCS#8 format. Also used in creating PKCS#12 shrouded key bags. See RFC 5208. More...
int	wc_EncryptPKCS8Key (byte *key, word32 keySz, byte *out, word32 *outSz, const char *password, int passwordSz, int vPKCS, int pbeOid, int encAlgId, byte *salt, word32 saltSz, int itt, WC_RNG *rng, void *heap)
	This function takes in an unencrypted PKCS#8 DER key (e.g. one created by wc_CreatePKCS8Key) and converts it to PKCS#8 encrypted format. The resulting encrypted key can be decrypted using wc_DecryptPKCS8Key. See RFC 5208. More...
int	wc_DecryptPKCS8Key (byte *input, word32 sz, const char *password, int passwordSz)
	This function takes an encrypted PKCS#8 DER key and decrypts it to PKCS#8 unencrypted DER. Undoes the encryption done by wc_EncryptPKCS8Key. See RFC5208. The input buffer is overwritten with the decrypted data. More...
int	wc_CreateEncryptedPKCS8Key (byte *key, word32 keySz, byte *out, word32 *outSz, const char *password, int passwordSz, int vPKCS, int pbeOid, int encAlgId, byte *salt, word32 saltSz, int itt, WC_RNG *rng, void *heap)
	This function takes a traditional, DER key, converts it to PKCS#8 format, and encrypts it. It uses wc_CreatePKCS8Key and wc_EncryptPKCS8Key to do this. More...
void	wc_InitDecodedCert (struct DecodedCert *cert, const byte *source, word32 inSz, void *heap)
	This function initializes the DecodedCert pointed to by the "cert" parameter. It saves the "source" pointer to a DER-encoded certificate of length "inSz." This certificate can be parsed by a subsequent call to wc_ParseCert. More...
int	wc_ParseCert (DecodedCert *cert, int type, int verify, void *cm)
	This function parses the DER-encoded certificate saved in the DecodedCert object and populates the fields of that object. The DecodedCert must have been initialized with a prior call to wc_InitDecodedCert. This function takes an optional pointer to a CertificateManager object, which is used to populate the certificate authority information of the DecodedCert, if the CA is found in the CertificateManager. More...
void	wc_FreeDecodedCert (struct DecodedCert *cert)
	This function frees a DecodedCert that was previously initialized with wc_InitDecodedCert. More...
int	wc_SetTimeCb (wc_time_cb f)
	This function registers a time callback that will be used anytime wolfSSL needs to get the current time. The prototype of the callback should be the same as the "time" function from the C standard library. More...
time_t	wc_Time (time_t *t)
	This function gets the current time. By default, it uses the XTIME macro, which varies between platforms. The user can use a function of their choosing instead via the wc_SetTimeCb function. More...
int	wc_SetCustomExtension (Cert *cert, int critical, const char *oid, const byte *der, word32 derSz)
	This function injects a custom extension in to an X.509 certificate. note: The content at the address pointed to by any of the parameters that are pointers must not be modified until the certificate is generated and you have the der output. This function does NOT copy the contents to another buffer. More...
int	wc_SetUnknownExtCallback (DecodedCert *cert, wc_UnknownExtCallback cb)
	This function registers a callback that will be used anytime wolfSSL encounters an unknown X.509 extension in a certificate while parsing a certificate. The prototype of the callback should be: More...
int	wc_CheckCertSigPubKey (const byte *cert, word32 certSz, void *heap, const byte *pubKey, word32 pubKeySz, int pubKeyOID)
	This function verifies the signature in the der form of an X.509 certificate against a public key. The public key is expected to be the full subject public key info in der form. More...
int	wc_Asn1PrintOptions_Init (Asn1PrintOptions *opts)
	This function initializes the ASN.1 print options. More...
int	wc_Asn1PrintOptions_Set (Asn1PrintOptions *opts, enum Asn1PrintOpt opt, word32 val)
	This function sets a print option into an ASN.1 print options object. More...
int	wc_Asn1_Init (Asn1 *asn1)
	This function initializes an ASN.1 parsing object. More...
int	wc_Asn1_SetFile (Asn1 *asn1, XFILE file)
	This function sets the file to use when printing into an ASN.1 parsing object. More...
int	wc_Asn1_PrintAll (Asn1 *asn1, Asn1PrintOptions *opts, unsigned char *data, word32 len)
	Print all ASN.1 items. More...

Detailed Description

Function Documentation

wc_Asn1_Init()

int wc_Asn1_Init

(

Asn1 *

asn1

)

This function initializes an ASN.1 parsing object.

Returns

0 on success.

BAD_FUNC_ARG when asn1 is NULL.

Parameters

asn1	ASN.1 parse object.

Example

Asn1 asn1;
 
// Initialize ASN.1 parse object before use.
wc_Asn1_Init(&asn1);

See also

wc_Asn1_SetFile

wc_Asn1_PrintAll

wc_Asn1_PrintAll()

int wc_Asn1_PrintAll	(	Asn1 *	asn1,
		Asn1PrintOptions *	opts,
		unsigned char *	data,
		word32	len
	)

Print all ASN.1 items.

Returns

0 on success.

BAD_FUNC_ARG when asn1 or opts is NULL.

ASN_LEN_E when ASN.1 item's length too long.

ASN_DEPTH_E when end offset invalid.

ASN_PARSE_E when not all of an ASN.1 item parsed.

Parameters

asn1	The ASN.1 parse object.
opts	The ASN.1 print options.
data	Buffer containing BER/DER data to print.
len	Length of data to print in bytes.

Asn1PrintOptions opts;
Asn1 asn1;
unsigned char data[] = { Initialize with DER/BER data };
word32 len = sizeof(data);
 
// Initialize ASN.1 print options before use.
wc_Asn1PrintOptions_Init(&opt);
// Set the number of indents when printing tag name to be 1.
wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);
 
// Initialize ASN.1 parse object before use.
wc_Asn1_Init(&asn1);
// Set standard out to be the file descriptor to write to.
wc_Asn1_SetFile(&asn1, stdout);
// Print all ASN.1 items in buffer with the specified print options.
wc_Asn1_PrintAll(&asn1, &opts, data, len);

See also

wc_Asn1_Init

wc_Asn1_SetFile

wc_Asn1_SetFile()

int wc_Asn1_SetFile	(	Asn1 *	asn1,
		XFILE	file
	)

This function sets the file to use when printing into an ASN.1 parsing object.

Returns

0 on success.

BAD_FUNC_ARG when asn1 is NULL.

BAD_FUNC_ARG when file is XBADFILE.

Parameters

asn1	The ASN.1 parse object.
file	File to print to.

Example

Asn1 asn1;
 
// Initialize ASN.1 parse object before use.
wc_Asn1_Init(&asn1);
// Set standard out to be the file descriptor to write to.
wc_Asn1_SetFile(&asn1, stdout);

See also

wc_Asn1_Init

wc_Asn1_PrintAll

wc_Asn1PrintOptions_Init()

int wc_Asn1PrintOptions_Init

(

Asn1PrintOptions *

opts

)

This function initializes the ASN.1 print options.

Returns

0 on success.

BAD_FUNC_ARG when asn1 is NULL.

Parameters

opts	The ASN.1 options for printing.

Example

Asn1PrintOptions opt;
 
// Initialize ASN.1 print options before use.
wc_Asn1PrintOptions_Init(&opt);

See also

wc_Asn1PrintOptions_Set

wc_Asn1_PrintAll

wc_Asn1PrintOptions_Set()

int wc_Asn1PrintOptions_Set	(	Asn1PrintOptions *	opts,
		enum Asn1PrintOpt	opt,
		word32	val
	)

This function sets a print option into an ASN.1 print options object.

Returns

0 on success.

BAD_FUNC_ARG when asn1 is NULL.

BAD_FUNC_ARG when val is out of range for option.

Parameters

opts	The ASN.1 options for printing.
opt	An option to set value for.
val	The value to set.

Example

Asn1PrintOptions opt;
 
// Initialize ASN.1 print options before use.
wc_Asn1PrintOptions_Init(&opt);
// Set the number of indents when printing tag name to be 1.
wc_Asn1PrintOptions_Set(&opt, ASN1_PRINT_OPT_INDENT, 1);

See also

wc_Asn1PrintOptions_Init

wc_Asn1_PrintAll

wc_CertFree()

void wc_CertFree

(

Cert *

cert

)

This function frees the memory allocated for a cert structure by a previous call to wc_CertNew().

Returns

None.

Parameters

A	pointer to the cert structure to free.

Example

Cert*   myCert;
 
myCert = wc_CertNew(NULL);
 
// Perform cert operations.
 
wc_CertFree(myCert);

See also

wc_InitCert

wc_MakeCert

wc_CertNew

wc_CertNew()

Cert* wc_CertNew

(

void *

heap

)

This function allocates a new Cert structure for use during cert operations without the application having to allocate the structure itself. The Cert structure is also initialized by this function thus removing the need to call wc_InitCert(). When the application is finished using the allocated Cert structure wc_CertFree() must be called.

Returns

pointer If successful the call will return a pointer to the newly allocated and initialized Cert.

NULL On a memory allocation failure.

Parameters

A	pointer to the heap used for dynamic allocation. Can be NULL.

Example

Cert*   myCert;
 
myCert = wc_CertNew(NULL);
if (myCert == NULL) {
    // Cert creation failure
}

See also

wc_InitCert

wc_MakeCert

wc_CertFree

wc_CheckCertSigPubKey()

int wc_CheckCertSigPubKey	(	const byte *	cert,
		word32	certSz,
		void *	heap,
		const byte *	pubKey,
		word32	pubKeySz,
		int	pubKeyOID
	)

This function verifies the signature in the der form of an X.509 certificate against a public key. The public key is expected to be the full subject public key info in der form.

Returns

0 Returned on success.

Other negative values on failure.

Parameters

cert	The der encoding of the X.509 certificate.
certSz	The size in bytes of cert.
heap	A pointer to the heap used for dynamic allocation. Can be NULL.
pubKey	The der encoding of the public key.
pubKeySz	The size in bytes of pubKey.
pubKeyOID	OID identifying the algorithm of the public key. (ie: ECDSAk, DSAk or RSAk)

wc_CreateEncryptedPKCS8Key()

int wc_CreateEncryptedPKCS8Key	(	byte *	key,
		word32	keySz,
		byte *	out,
		word32 *	outSz,
		const char *	password,
		int	passwordSz,
		int	vPKCS,
		int	pbeOid,
		int	encAlgId,
		byte *	salt,
		word32	saltSz,
		int	itt,
		WC_RNG *	rng,
		void *	heap
	)

This function takes a traditional, DER key, converts it to PKCS#8 format, and encrypts it. It uses wc_CreatePKCS8Key and wc_EncryptPKCS8Key to do this.

Returns

The size of the encrypted key placed in out on success.

LENGTH_ONLY_E if out is NULL, with required output buffer size in outSz.

Other negative values on failure.

Parameters

key	Buffer with traditional DER key.
keySz	Size of key buffer.
out	Buffer to place result in. If NULL, required out buffer size returned in outSz.
outSz	Size of out buffer.
password	The password to use for the password-based encryption algorithm.
passwordSz	The length of the password (not including the NULL terminator).
vPKCS	The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
pbeOid	The OID of the PBE scheme to use (e.g. PBES2 or one of the OIDs for PBES1 in RFC 2898 A.3).
encAlgId	The encryption algorithm ID to use (e.g. AES256CBCb).
salt	The salt buffer to use. If NULL, a random salt will be used.
saltSz	The length of the salt buffer. Can be 0 if passing NULL for salt.
itt	The number of iterations to use for the KDF.
rng	A pointer to an initialized WC_RNG object.
heap	A pointer to the heap used for dynamic allocation. Can be NULL.

Example

byte* key;            // Traditional private key (DER formatted).
word32 keySz;         // Size of key.
byte* pkcs8Enc;       // Encrypted PKCS#8 key.
word32 pkcs8EncSz;    // Size of pkcs8Enc.
const char* password; // Password to use for encryption.
int passwordSz;       // Length of password (not including NULL terminator).
WC_RNG rng;
 
// The following produces an encrypted, PKCS#8 version of key in pkcs8Enc.
// The encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5
// and the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more
// on PKCS#5.
ret = wc_CreateEncryptedPKCS8Key(key, keySz, pkcs8Enc, &pkcs8EncSz,
        password, passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
        WC_PKCS12_ITT_DEFAULT, &rng, NULL);

See also

wc_GetPkcs8TraditionalOffset

wc_CreatePKCS8Key

wc_EncryptPKCS8Key

wc_DecryptPKCS8Key

wc_CreatePKCS8Key()

int wc_CreatePKCS8Key	(	byte *	out,
		word32 *	outSz,
		byte *	key,
		word32	keySz,
		int	algoID,
		const byte *	curveOID,
		word32	oidSz
	)

This function takes in a DER private key and converts it to PKCS#8 format. Also used in creating PKCS#12 shrouded key bags. See RFC 5208.

Returns

The size of the PKCS#8 key placed into out on success.

LENGTH_ONLY_E if out is NULL, with required output buffer size in outSz.

Other negative values on failure.

Parameters

out	Buffer to place result in. If NULL, required out buffer size returned in outSz.
outSz	Size of out buffer.
key	Buffer with traditional DER key.
keySz	Size of key buffer.
algoID	Algorithm ID (e.g. RSAk).
curveOID	ECC curve OID if used. Should be NULL for RSA keys.
oidSz	Size of curve OID. Is set to 0 if curveOID is NULL.

Example

ecc_key eccKey;              // wolfSSL ECC key object.
byte* der;                   // DER-encoded ECC key.
word32 derSize;              // Size of der.
const byte* curveOid = NULL; // OID of curve used by eccKey.
word32 curveOidSz = 0;       // Size of curve OID.
byte* pkcs8;                 // Output buffer for PKCS#8 key.
word32 pkcs8Sz;              // Size of output buffer.
 
derSize = wc_EccKeyDerSize(&eccKey, 1);
...
derSize = wc_EccKeyToDer(&eccKey, der, derSize);
...
ret = wc_ecc_get_oid(eccKey.dp->oidSum, &curveOid, &curveOidSz);
...
ret = wc_CreatePKCS8Key(NULL, &pkcs8Sz, der,
    derSize, ECDSAk, curveOid, curveOidSz); // Get size needed in pkcs8Sz.
...
ret = wc_CreatePKCS8Key(pkcs8, &pkcs8Sz, der,
    derSize, ECDSAk, curveOid, curveOidSz);

See also

wc_GetPkcs8TraditionalOffset

wc_EncryptPKCS8Key

wc_DecryptPKCS8Key

wc_CreateEncryptedPKCS8Key

wc_Curve25519KeyDecode()

int wc_Curve25519KeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		curve25519_key *	key,
		word32	inSz
	)

This function decodes a Curve25519 key from a DER encoded buffer. It can decode either a private key, a public key, or both.

Returns

0 Success

BAD_FUNC_ARG Returns if input, inOutIdx or key is null

ASN_PARSE_E Returns if there is an error parsing the DER encoded data

ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or the DER key contains other issues despite being properly formatted.

BUFFER_E Returns if the input buffer is too small to contain a valid DER encoded key.

Parameters

input	Pointer to buffer containing DER encoded key
inOutIdx	Index to start reading input buffer from. On output, index is set to last position parsed of input buffer.
key	Pointer to curve25519_key structure to store decoded key
inSz	Size of input DER buffer

See also

wc_Curve25519PrivateKeyDecode

wc_Curve25519PublicKeyDecode

Example

byte der[] = { // DER encoded key };
word32 idx = 0;
curve25519_key key;
wc_curve25519_init(&key);
if (wc_Curve25519KeyDecode(der, &idx, &key, sizeof(der)) != 0) {
    // Error decoding key
}

wc_Curve25519KeyToDer()

int wc_Curve25519KeyToDer	(	curve25519_key *	key,
		byte *	output,
		word32	inLen,
		int	withAlg
	)

This function encodes a Curve25519 key to DER format. It can encode either a private key, a public key, or both.

Returns

>0 Success, length of DER encoding

BAD_FUNC_ARG Returns if key or output is null

MEMORY_E Returns if there is an allocation failure

BUFFER_E Returns if output buffer is too small

Parameters

key	Pointer to curve25519_key structure containing key to encode
output	Buffer to hold DER encoding
inLen	Size of output buffer
withAlg	Whether to include algorithm identifier in the DER encoding

See also

wc_Curve25519PrivateKeyToDer

wc_Curve25519PublicKeyToDer

Example

curve25519_key key;
wc_curve25519_init(&key);
...
int derSz = 128; // Some appropriate size for output DER
byte der[derSz];
wc_Curve25519KeyToDer(&key, der, derSz, 1);

wc_Curve25519PrivateKeyDecode()

int wc_Curve25519PrivateKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		curve25519_key *	key,
		word32	inSz
	)

This function decodes a Curve25519 private key (only) from a DER encoded buffer.

Returns

0 Success

BAD_FUNC_ARG Returns if input, inOutIdx or key is null

ASN_PARSE_E Returns if there is an error parsing the DER encoded data

ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or the DER key contains other issues despite being properly formatted.

BUFFER_E Returns if the input buffer is too small to contain a valid DER encoded key.

Parameters

input	Pointer to buffer containing DER encoded private key
inOutIdx	Index to start reading input buffer from. On output, index is set to last position parsed of input buffer.
key	Pointer to curve25519_key structure to store decoded key
inSz	Size of input DER buffer

See also

wc_Curve25519KeyDecode

wc_Curve25519PublicKeyDecode

Example

byte der[] = { // DER encoded key };
word32 idx = 0;
curve25519_key key;
wc_curve25519_init(&key);
 
if (wc_Curve25519PrivateKeyDecode(der, &idx, &key, sizeof(der)) != 0) {
    // Error decoding private key
}

wc_Curve25519PrivateKeyToDer()

int wc_Curve25519PrivateKeyToDer	(	curve25519_key *	key,
		byte *	output,
		word32	inLen
	)

This function encodes a Curve25519 private key to DER format. If the input key structure contains a public key, it will be ignored.

Returns

>0 Success, length of DER encoding

BAD_FUNC_ARG Returns if key or output is null

MEMORY_E Returns if there is an allocation failure

BUFFER_E Returns if output buffer is too small

Parameters

key	Pointer to curve25519_key structure containing private key to encode
output	Buffer to hold DER encoding
inLen	Size of output buffer

See also

wc_Curve25519KeyToDer

wc_Curve25519PublicKeyToDer

Example

curve25519_key key;
wc_curve25519_init(&key);
...
int derSz = 128; // Some appropriate size for output DER
byte der[derSz];
wc_Curve25519PrivateKeyToDer(&key, der, derSz);

wc_Curve25519PublicKeyDecode()

int wc_Curve25519PublicKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		curve25519_key *	key,
		word32	inSz
	)

This function decodes a Curve25519 public key (only) from a DER encoded buffer.

Returns

0 Success

BAD_FUNC_ARG Returns if input, inOutIdx or key is null

ASN_PARSE_E Returns if there is an error parsing the DER encoded data

ECC_BAD_ARG_E Returns if the key length is not CURVE25519_KEYSIZE or the DER key contains other issues despite being properly formatted.

BUFFER_E Returns if the input buffer is too small to contain a valid DER encoded key.

Parameters

input	Pointer to buffer containing DER encoded public key
inOutIdx	Index to start reading input buffer from. On output, index is set to last position parsed of input buffer.
key	Pointer to curve25519_key structure to store decoded key
inSz	Size of input DER buffer

See also

wc_Curve25519KeyDecode

wc_Curve25519PrivateKeyDecode

Example

byte der[] = { // DER encoded key };
word32 idx = 0;
curve25519_key key;
wc_curve25519_init(&key);
if (wc_Curve25519PublicKeyDecode(der, &idx, &key, sizeof(der)) != 0) {
    // Error decoding public key
}

wc_Curve25519PublicKeyToDer()

int wc_Curve25519PublicKeyToDer	(	curve25519_key *	key,
		byte *	output,
		word32	inLen,
		int	withAlg
	)

This function encodes a Curve25519 public key to DER format. If the input key structure contains a private key, it will be ignored.

Returns

>0 Success, length of DER encoding

BAD_FUNC_ARG Returns if key or output is null

MEMORY_E Returns if there is an allocation failure

BUFFER_E Returns if output buffer is too small

Parameters

key	Pointer to curve25519_key structure containing public key to encode
output	Buffer to hold DER encoding
inLen	Size of output buffer
withAlg	Whether to include algorithm identifier in the DER encoding

See also

wc_Curve25519KeyToDer

wc_Curve25519PrivateKeyToDer

Example

curve25519_key key;
wc_curve25519_init(&key);
...
int derSz = 128; // Some appropriate size for output DER
byte der[derSz];
wc_Curve25519PublicKeyToDer(&key, der, derSz, 1);

wc_DecryptPKCS8Key()

int wc_DecryptPKCS8Key	(	byte *	input,
		word32	sz,
		const char *	password,
		int	passwordSz
	)

This function takes an encrypted PKCS#8 DER key and decrypts it to PKCS#8 unencrypted DER. Undoes the encryption done by wc_EncryptPKCS8Key. See RFC5208. The input buffer is overwritten with the decrypted data.

Returns

The length of the decrypted buffer on success.

Negative values on failure.

Parameters

input	On input, buffer containing encrypted PKCS#8 key. On successful output, contains the decrypted key.
sz	Size of the input buffer.
password	The password used to encrypt the key.
passwordSz	The length of the password (not including NULL terminator).

Example

byte* pkcs8Enc;       // Encrypted PKCS#8 key made with wc_EncryptPKCS8Key.
word32 pkcs8EncSz;    // Size of pkcs8Enc.
const char* password; // Password to use for decryption.
int passwordSz;       // Length of password (not including NULL terminator).
 
ret = wc_DecryptPKCS8Key(pkcs8Enc, pkcs8EncSz, password, passwordSz);

See also

wc_GetPkcs8TraditionalOffset

wc_CreatePKCS8Key

wc_EncryptPKCS8Key

wc_CreateEncryptedPKCS8Key

wc_DerToPem()

int wc_DerToPem	(	const byte *	der,
		word32	derSz,
		byte *	output,
		word32	outputSz,
		int	type
	)

This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output.

Returns

Success On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated.

BAD_FUNC_ARG Returned if there is an error parsing the der file and storing it as a pem file

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_INPUT_E Returned in the case of a base64 encoding error

BUFFER_E May be returned if the output buffer is too small to store the pem formatted certificate

Parameters

der	pointer to the buffer of the certificate to convert
derSz	size of the the certificate to convert
output	pointer to the buffer in which to store the pem formatted certificate
outSz	size of the buffer in which to store the pem formatted certificate
type	the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.

Example

byte* der;
// initialize der with certificate
byte* pemFormatted[FOURK_BUF];
 
word32 pemSz;
pemSz = wc_DerToPem(der, derSz,pemFormatted,FOURK_BUF, CERT_TYPE);

See also

wc_PemCertToDer

wc_DerToPemEx()

int wc_DerToPemEx	(	const byte *	der,
		word32	derSz,
		byte *	output,
		word32	outputSz,
		byte *	cipherIno,
		int	type
	)

This function converts a der formatted input certificate, contained in the der buffer, into a pem formatted output certificate, contained in the output buffer. It should be noted that this is not an in place conversion, and a separate buffer must be utilized to store the pem formatted output. Allows setting cipher info.

Returns

Success On successfully making a pem certificate from the input der cert, returns the size of the pem cert generated.

BAD_FUNC_ARG Returned if there is an error parsing the der file and storing it as a pem file

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_INPUT_E Returned in the case of a base64 encoding error

BUFFER_E May be returned if the output buffer is too small to store the pem formatted certificate

Parameters

der	pointer to the buffer of the certificate to convert
derSz	size of the the certificate to convert
output	pointer to the buffer in which to store the pem formatted certificate
outSz	size of the buffer in which to store the pem formatted certificate
cipher_inf	Additional cipher information.
type	the type of certificate to generate. Valid types are: CERT_TYPE, PRIVATEKEY_TYPE, ECC_PRIVATEKEY_TYPE, and CERTREQ_TYPE.

Example

byte* der;
// initialize der with certificate
byte* pemFormatted[FOURK_BUF];
 
word32 pemSz;
byte* cipher_info[] { Additional cipher info. }
pemSz = wc_DerToPemEx(der, derSz, pemFormatted, FOURK_BUF, cipher_info, CERT_TYPE);

See also

wc_PemCertToDer

wc_EccKeyToDer()

int wc_EccKeyToDer	(	ecc_key *	key,
		byte *	output,
		word32	inLen
	)

This function writes a private ECC key to der format.

Returns

Success On successfully writing the ECC key to der format, returns the length written to the buffer

BAD_FUNC_ARG Returned if key or output is null, or inLen equals zero

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the converted certificate is too large to store in the output buffer

ASN_UNKNOWN_OID_E Returned if the ECC key used is of an unknown type

MP_MEM Returned if there is an error in the math library used while parsing the private key

MP_VAL Returned if there is an error in the math library used while parsing the private key

MP_RANGE Returned if there is an error in the math library used while parsing the private key

Parameters

key	pointer to the buffer containing the input ecc key
output	pointer to a buffer in which to store the der formatted key
inLen	the length of the buffer in which to store the der formatted key

Example

int derSz;
ecc_key key;
// initialize and make key
byte der[FOURK_BUF];
// store der formatted key here
 
derSz = wc_EccKeyToDer(&key, der, FOURK_BUF);
if(derSz < 0) {
    // error converting ecc key to der buffer
}

See also

wc_RsaKeyToDer

wc_EccPrivateKeyDecode()

int wc_EccPrivateKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		ecc_key *	key,
		word32	inSz
	)

This function reads in an ECC private key from the input buffer, input, parses the private key, and uses it to generate an ecc_key object, which it stores in key.

Returns

0 On successfully decoding the private key and storing the result in the ecc_key struct

ASN_PARSE_E: Returned if there is an error parsing the der file and storing it as a pem file

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the certificate to convert is large than the specified max certificate size

ASN_OBJECT_ID_E Returned if the certificate encoding has an invalid object id

ECC_CURVE_OID_E Returned if the ECC curve of the provided key is not supported

ECC_BAD_ARG_E Returned if there is an error in the ECC key format

NOT_COMPILED_IN Returned if the private key is compressed, and no compression key is provided

MP_MEM Returned if there is an error in the math library used while parsing the private key

MP_VAL Returned if there is an error in the math library used while parsing the private key

MP_RANGE Returned if there is an error in the math library used while parsing the private key

Parameters

input	pointer to the buffer containing the input private key
inOutIdx	pointer to a word32 object containing the index in the buffer at which to start
key	pointer to an initialized ecc object, on which to store the decoded private key
inSz	size of the input buffer containing the private key

Example

int ret, idx=0;
ecc_key key; // to store key in
 
byte* tmp; // tmp buffer to read key from
tmp = (byte*) malloc(FOURK_BUF);
 
int inSz;
inSz = fread(tmp, 1, FOURK_BUF, privateKeyFile);
// read key into tmp buffer
 
wc_ecc_init(&key); // initialize key
ret = wc_EccPrivateKeyDecode(tmp, &idx, &key, (word32)inSz);
if(ret < 0) {
    // error decoding ecc key
}

See also

wc_RSA_PrivateKeyDecode

wc_EccPublicKeyDecode()

int wc_EccPublicKeyDecode	(	const byte *	input,
		word32 *	inOutIdx,
		ecc_key *	key,
		word32	inSz
	)

Decodes an ECC public key from an input buffer. It will parse an ASN sequence to retrieve the ECC key.

Returns

0 Success

BAD_FUNC_ARG Returns if any arguments are null.

ASN_PARSE_E Returns if there is an error parsing

ASN_ECC_KEY_E Returns if there is an error importing the key. See wc_ecc_import_x963 for possible reasons.

Parameters

input	Buffer containing DER encoded key to decode.
inOutIdx	Index to start reading input buffer from. On output, index is set to last position parsed of input buffer.
key	Pointer to ecc_key struct to store the public key.
inSz	Size of the input buffer.

Example

int ret;
word32 idx = 0;
byte buff[] = { // initialize with key };
ecc_key pubKey;
wc_ecc_init(&pubKey);
if ( wc_EccPublicKeyDecode(buff, &idx, &pubKey, sizeof(buff)) != 0) {
        // error decoding key
}

See also

wc_ecc_import_x963

wc_EccPublicKeyToDer()

int wc_EccPublicKeyToDer	(	ecc_key *	key,
		byte *	output,
		word32	inLen,
		int	with_AlgCurve
	)

This function converts the ECC public key to DER format. It returns the size of buffer used. The public ECC key in DER format is stored in output buffer. The with_AlgCurve flag will include a header that has the Algorithm and Curve information.

Returns

>0 Success, size of buffer used

BAD_FUNC_ARG Returned if output or key is null.

LENGTH_ONLY_E Error in getting ECC public key size.

BUFFER_E Returned when output buffer is too small.

Parameters

key	Pointer to ECC key
output	Pointer to output buffer to write to.
inLen	Size of buffer.
with_AlgCurve	a flag for when to include a header that has the Algorithm and Curve information.

Example

ecc_key key;
wc_ecc_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
int derSz = // Some appropriate size for der;
byte der[derSz];
 
if(wc_EccPublicKeyToDer(&key, der, derSz, 1) < 0)
{
    // Error converting ECC public key to der
}

See also

wc_EccKeyToDer

wc_EccPrivateKeyDecode

wc_EccPublicKeyToDer_ex()

int wc_EccPublicKeyToDer_ex	(	ecc_key *	key,
		byte *	output,
		word32	inLen,
		int	with_AlgCurve,
		int	comp
	)

This function converts the ECC public key to DER format. It returns the size of buffer used. The public ECC key in DER format is stored in output buffer. The with_AlgCurve flag will include a header that has the Algorithm and Curve information. The comp parameter determines if the public key will be exported as compressed.

Returns

>0 Success, size of buffer used

BAD_FUNC_ARG Returned if output or key is null.

LENGTH_ONLY_E Error in getting ECC public key size.

BUFFER_E Returned when output buffer is too small.

Parameters

key	Pointer to ECC key
output	Pointer to output buffer to write to.
inLen	Size of buffer.
with_AlgCurve	a flag for when to include a header that has the Algorithm and Curve information.
comp	If 1 (non-zero) the ECC public key will be written in compressed form. If 0 it will be written in an uncompressed format.

Example

ecc_key key;
wc_ecc_init(&key);
WC_RNG rng;
wc_InitRng(&rng);
wc_ecc_make_key(&rng, 32, &key);
int derSz = // Some appropriate size for der;
byte der[derSz];
 
// Write out a compressed ECC key
if(wc_EccPublicKeyToDer_ex(&key, der, derSz, 1, 1) < 0)
{
    // Error converting ECC public key to der
}

See also

wc_EccKeyToDer

wc_EccPublicKeyDecode

wc_EncodeSignature()

word32 wc_EncodeSignature	(	byte *	out,
		const byte *	digest,
		word32	digSz,
		int	hashOID
	)

This function encodes a digital signature into the output buffer, and returns the size of the encoded signature created.

Returns

Success On successfully writing the encoded signature to output, returns the length written to the buffer

Parameters

out	pointer to the buffer where the encoded signature will be written
digest	pointer to the digest to use to encode the signature
digSz	the length of the buffer containing the digest
hashOID	OID identifying the hash type used to generate the signature. Valid options, depending on build configurations, are: SHAh, SHA256h, SHA384h, SHA512h, MD2h, MD5h, DESb, DES3b, CTC_MD5wRSA, CTC_SHAwRSA, CTC_SHA256wRSA, CTC_SHA384wRSA, CTC_SHA512wRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, CTC_SHA384wECDSA, and CTC_SHA512wECDSA.

int signSz;
byte encodedSig[MAX_ENCODED_SIG_SZ];
Sha256 sha256;
// initialize sha256 for hashing
 
byte* dig = = (byte*)malloc(WC_SHA256_DIGEST_SIZE);
// perform hashing and hash updating so dig stores SHA-256 hash
// (see wc_InitSha256, wc_Sha256Update and wc_Sha256Final)
signSz = wc_EncodeSignature(encodedSig, dig, WC_SHA256_DIGEST_SIZE, SHA256h);

See also

none

wc_EncryptPKCS8Key()

int wc_EncryptPKCS8Key	(	byte *	key,
		word32	keySz,
		byte *	out,
		word32 *	outSz,
		const char *	password,
		int	passwordSz,
		int	vPKCS,
		int	pbeOid,
		int	encAlgId,
		byte *	salt,
		word32	saltSz,
		int	itt,
		WC_RNG *	rng,
		void *	heap
	)

This function takes in an unencrypted PKCS#8 DER key (e.g. one created by wc_CreatePKCS8Key) and converts it to PKCS#8 encrypted format. The resulting encrypted key can be decrypted using wc_DecryptPKCS8Key. See RFC 5208.

Returns

The size of the encrypted key placed in out on success.

LENGTH_ONLY_E if out is NULL, with required output buffer size in outSz.

Other negative values on failure.

Parameters

key	Buffer with traditional DER key.
keySz	Size of key buffer.
out	Buffer to place result in. If NULL, required out buffer size returned in outSz.
outSz	Size of out buffer.
password	The password to use for the password-based encryption algorithm.
passwordSz	The length of the password (not including the NULL terminator).
vPKCS	The PKCS version to use. Can be 1 for PKCS12 or PKCS5.
pbeOid	The OID of the PBE scheme to use (e.g. PBES2 or one of the OIDs for PBES1 in RFC 2898 A.3).
encAlgId	The encryption algorithm ID to use (e.g. AES256CBCb).
salt	The salt buffer to use. If NULL, a random salt will be used.
saltSz	The length of the salt buffer. Can be 0 if passing NULL for salt.
itt	The number of iterations to use for the KDF.
rng	A pointer to an initialized WC_RNG object.
heap	A pointer to the heap used for dynamic allocation. Can be NULL.

Example

byte* pkcs8;          // Unencrypted PKCS#8 key.
word32 pkcs8Sz;       // Size of pkcs8.
byte* pkcs8Enc;       // Encrypted PKCS#8 key.
word32 pkcs8EncSz;    // Size of pkcs8Enc.
const char* password; // Password to use for encryption.
int passwordSz;       // Length of password (not including NULL terminator).
WC_RNG rng;
 
// The following produces an encrypted version of pkcs8 in pkcs8Enc. The
// encryption uses password-based encryption scheme 2 (PBE2) from PKCS#5 and
// the AES cipher in CBC mode with a 256-bit key. See RFC 8018 for more on
// PKCS#5.
ret = wc_EncryptPKCS8Key(pkcs8, pkcs8Sz, pkcs8Enc, &pkcs8EncSz, password,
        passwordSz, PKCS5, PBES2, AES256CBCb, NULL, 0,
        WC_PKCS12_ITT_DEFAULT, &rng, NULL);

See also

wc_GetPkcs8TraditionalOffset

wc_CreatePKCS8Key

wc_DecryptPKCS8Key

wc_CreateEncryptedPKCS8Key

wc_FreeDecodedCert()

void wc_FreeDecodedCert

(

struct DecodedCert *

cert

)

This function frees a DecodedCert that was previously initialized with wc_InitDecodedCert.

Parameters

cert	Pointer to an initialized DecodedCert object.

Example

int ret;
DecodedCert decodedCert; // Decoded certificate object.
byte* certBuf;           // DER-encoded certificate buffer.
word32 certBufSz;        // Size of certBuf in bytes.
 
wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
if (ret != 0) {
    fprintf(stderr, "wc_ParseCert failed.\n");
}
wc_FreeDecodedCert(&decodedCert);

See also

wc_InitDecodedCert

wc_ParseCert

wc_GetCTC_HashOID()

int wc_GetCTC_HashOID

(

int

type

)

This function returns the hash OID that corresponds to a hashing type. For example, when given the type: WC_SHA512, this function returns the identifier corresponding to a SHA512 hash, SHA512h.

Returns

Success On success, returns the OID corresponding to the appropriate hash to use with that encryption type.

0 Returned if an unrecognized hash type is passed in as argument.

Parameters

type	the hash type for which to find the OID. Valid options, depending on build configuration, include: WC_MD5, WC_SHA, WC_SHA256, WC_SHA384, WC_SHA512, WC_SHA3_224, WC_SHA3_256, WC_SHA3_384 or WC_SHA3_512

Example

int hashOID;
 
hashOID = wc_GetCTC_HashOID(WC_SHA512);
if (hashOID == 0) {
    // WOLFSSL_SHA512 not defined
}

See also

none

wc_GetPkcs8TraditionalOffset()

int wc_GetPkcs8TraditionalOffset	(	byte *	input,
		word32 *	inOutIdx,
		word32	sz
	)

This function finds the beginning of the traditional private key inside a PKCS#8 unencrypted buffer.

Returns

Length of traditional private key on success.

Negative values on failure.

Parameters

input	Buffer containing unencrypted PKCS#8 private key.
inOutIdx	Index into the input buffer. On input, it should be a byte offset to the beginning of the the PKCS#8 buffer. On output, it will be the byte offset to the traditional private key within the input buffer.
sz	The number of bytes in the input buffer.

Example

byte* pkcs8Buf; // Buffer containing PKCS#8 key.
word32 idx = 0;
word32 sz; // Size of pkcs8Buf.
...
ret = wc_GetPkcs8TraditionalOffset(pkcs8Buf, &idx, sz);
// pkcs8Buf + idx is now the beginning of the traditional private key bytes.

See also

wc_CreatePKCS8Key

wc_EncryptPKCS8Key

wc_DecryptPKCS8Key

wc_CreateEncryptedPKCS8Key

wc_GetSubjectRaw()

int wc_GetSubjectRaw	(	byte **	subjectRaw,
		Cert *	cert
	)

This function gets the raw subject from the certificate structure.

Returns

0 Returned on successfully getting the subject from the certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

Parameters

subjectRaw	pointer-pointer to the raw subject upon successful return
cert	pointer to the cert from which to get the raw subject

Example

Cert myCert;
byte *subjRaw;
// initialize myCert
 
if(wc_GetSubjectRaw(&subjRaw, &myCert) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetSubjectRaw

wc_InitCert()

int wc_InitCert

(

Cert *

)

This function initializes a default cert, with the default options: version = 3 (0x2), serial = 0, sigType = SHA_WITH_RSA, issuer = blank, daysValid = 500, selfSigned = 1 (true) use subject as issuer, subject = blank.

Returns

none No returns.

Parameters

cert	pointer to an uninitialized cert structure to initialize

Example

Cert myCert;
wc_InitCert(&myCert);

See also

wc_MakeCert

wc_MakeCertReq

wc_InitDecodedCert()

void wc_InitDecodedCert	(	struct DecodedCert *	cert,
		const byte *	source,
		word32	inSz,
		void *	heap
	)

This function initializes the DecodedCert pointed to by the "cert" parameter. It saves the "source" pointer to a DER-encoded certificate of length "inSz." This certificate can be parsed by a subsequent call to wc_ParseCert.

Parameters

cert	Pointer to an allocated DecodedCert object.
source	Pointer to a DER-encoded certificate.
inSz	Length of the DER-encoded certificate in bytes.
heap	A pointer to the heap used for dynamic allocation. Can be NULL.

Example

DecodedCert decodedCert; // Decoded certificate object.
byte* certBuf;           // DER-encoded certificate buffer.
word32 certBufSz;        // Size of certBuf in bytes.
 
wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);

See also

wc_ParseCert

wc_FreeDecodedCert

wc_MakeCert()

int wc_MakeCert	(	Cert *	cert,
		byte *	derBuffer,
		word32	derSz,
		RsaKey *	rsaKey,
		ecc_key *	eccKey,
		WC_RNG *	rng
	)

Used to make CA signed certs. Called after the subject information has been entered. This function makes an x509 Certificate v3 RSA or ECC from a cert input. It then writes this cert to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate. The certificate must be initialized with wc_InitCert before this method is called.

Returns

Success On successfully making an x509 certificate from the specified input cert, returns the size of the cert generated.

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the provided derBuffer is too small to store the generated certificate

Others Additional error messages may be returned if the cert generation is not successful.

Parameters

cert	pointer to an initialized cert structure
derBuffer	pointer to the buffer in which to hold the generated cert
derSz	size of the buffer in which to store the cert
rsaKey	pointer to an RsaKey structure containing the rsa key used to generate the certificate
eccKey	pointer to an EccKey structure containing the ecc key used to generate the certificate
rng	pointer to the random number generator used to make the cert

Example

Cert myCert;
wc_InitCert(&myCert);
WC_RNG rng;
//initialize rng;
RsaKey key;
//initialize key;
byte * derCert = malloc(FOURK_BUF);
word32 certSz;
certSz = wc_MakeCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);

See also

wc_InitCert

wc_MakeCertReq

wc_MakeCertReq()

int wc_MakeCertReq	(	Cert *	cert,
		byte *	derBuffer,
		word32	derSz,
		RsaKey *	rsaKey,
		ecc_key *	eccKey
	)

This function makes a certificate signing request using the input certificate and writes the output to derBuffer. It takes in either an rsaKey or an eccKey to generate the certificate request. wc_SignCert() will need to be called after this function to sign the certificate request. Please see the wolfCrypt test application (./wolfcrypt/test/test.c) for an example usage of this function.

Returns

Success On successfully making an X.509 certificate request from the specified input cert, returns the size of the certificate request generated.

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the provided derBuffer is too small to store the generated certificate

Other Additional error messages may be returned if the certificate request generation is not successful.

Parameters

cert	pointer to an initialized cert structure
derBuffer	pointer to the buffer in which to hold the generated certificate request
derSz	size of the buffer in which to store the certificate request
rsaKey	pointer to an RsaKey structure containing the rsa key used to generate the certificate request
eccKey	pointer to an EccKey structure containing the ecc key used to generate the certificate request

Example

Cert myCert;
// initialize myCert
EccKey key;
//initialize key;
byte* derCert = (byte*)malloc(FOURK_BUF);
 
word32 certSz;
certSz = wc_MakeCertReq(&myCert, derCert, FOURK_BUF, NULL, &key);

See also

wc_InitCert

wc_MakeCert

wc_MakeSelfCert()

int wc_MakeSelfCert	(	Cert *	cert,
		byte *	derBuffer,
		word32	derSz,
		RsaKey *	key,
		WC_RNG *	rng
	)

This function is a combination of the previous two functions, wc_MakeCert and wc_SignCert for self signing (the previous functions may be used for CA requests). It makes a certificate, and then signs it, generating a self-signed certificate.

Returns

Success On successfully signing the certificate, returns the new size of the cert.

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the provided buffer is too small to store the generated certificate

Other Additional error messages may be returned if the cert generation is not successful.

Parameters

cert	pointer to the cert to make and sign
buffer	pointer to the buffer in which to hold the signed certificate
buffSz	size of the buffer in which to store the signed certificate
key	pointer to an RsaKey structure containing the rsa key to used to sign the certificate
rng	pointer to the random number generator used to generate and sign the certificate

Example

Cert myCert;
byte* derCert = (byte*)malloc(FOURK_BUF);
// initialize myCert, derCert
RsaKey key;
// initialize key;
WC_RNG rng;
// initialize rng
 
word32 certSz;
certSz = wc_MakeSelfCert(&myCert, derCert, FOURK_BUF, &key, NULL, &rng);

See also

wc_InitCert

wc_MakeCert

wc_SignCert

wc_ParseCert()

int wc_ParseCert	(	DecodedCert *	cert,
		int	type,
		int	verify,
		void *	cm
	)

This function parses the DER-encoded certificate saved in the DecodedCert object and populates the fields of that object. The DecodedCert must have been initialized with a prior call to wc_InitDecodedCert. This function takes an optional pointer to a CertificateManager object, which is used to populate the certificate authority information of the DecodedCert, if the CA is found in the CertificateManager.

Returns

0 on success.

Other negative values on failure.

Parameters

cert	Pointer to an initialized DecodedCert object.
type	Type of certificate. See the CertType enum in asn_public.h.
verify	Flag that, if set, indicates the user wants to verify the validity of the certificate.
cm	An optional pointer to a CertificateManager. Can be NULL.

Example

int ret;
DecodedCert decodedCert; // Decoded certificate object.
byte* certBuf;           // DER-encoded certificate buffer.
word32 certBufSz;        // Size of certBuf in bytes.
 
wc_InitDecodedCert(&decodedCert, certBuf, certBufSz, NULL);
ret = wc_ParseCert(&decodedCert, CERT_TYPE, NO_VERIFY, NULL);
if (ret != 0) {
    fprintf(stderr, "wc_ParseCert failed.\n");
}

See also

wc_InitDecodedCert

wc_FreeDecodedCert

wc_PemCertToDer()

int wc_PemCertToDer	(	const char *	fileName,
		unsigned char *	derBuf,
		int	derSz
	)

This function converts a pem certificate to a der certificate, and places the resulting certificate in the derBuf buffer provided.

Returns

Success On success returns the size of the derBuf generated

BUFFER_E Returned if the size of derBuf is too small to hold the certificate generated

MEMORY_E Returned if the call to XMALLOC fails

Parameters

fileName	path to the file containing a pem certificate to convert to a der certificate
derBuf	pointer to a char buffer in which to store the converted certificate
derSz	size of the char buffer in which to store the converted certificate

Example

char * file = “./certs/client-cert.pem”;
int derSz;
byte* der = (byte*)XMALLOC((8*1024), NULL, DYNAMIC_TYPE_CERT);
 
derSz = wc_PemCertToDer(file, der, (8*1024));
if (derSz <= 0) {
    //PemCertToDer error
}

See also

none

wc_PemPubKeyToDer()

int wc_PemPubKeyToDer	(	const char *	fileName,
		unsigned char *	derBuf,
		int	derSz
	)

Loads a PEM key from a file and converts to a DER encoded buffer.

Returns

0 Success

<0 Error

SSL_BAD_FILE There is a problem with opening the file.

MEMORY_E There is an error allocating memory for the file buffer.

BUFFER_E derBuf is not large enough to hold the converted key.

Parameters

fileName	Name of the file to load.
derBuf	Buffer for DER encoded key.
derSz	Size of DER buffer.

Example

char* some_file = "filename";
unsigned char der[];
 
if(wc_PemPubKeyToDer(some_file, der, sizeof(der)) != 0)
{
    //Handle Error
}

See also

wc_PubKeyPemToDer

wc_PubKeyPemToDer()

int wc_PubKeyPemToDer	(	const unsigned char *	pem,
		int	pemSz,
		unsigned char *	buff,
		int	buffSz
	)

Convert a PEM encoded public key to DER. Returns the number of bytes written to the buffer or a negative value for an error.

Returns

>0 Success, number of bytes written.

BAD_FUNC_ARG Returns if pem, buff, or buffSz are null

<0 An error occurred in the function.

Parameters

pem	PEM encoded key
pemSz	Size of pem
buff	Pointer to buffer for output.
buffSz	Size of buffer.

Example

byte some_pem[] = { Initialize with PEM key }
unsigned char out_buffer[1024]; // Ensure buffer is large enough to fit DER
 
if(wc_PubKeyPemToDer(some_pem, sizeof(some_pem), out_buffer,
sizeof(out_buffer)) < 0)
{
    // Handle error
}

See also

wc_PemPubKeyToDer

wc_SetAltNames()

int wc_SetAltNames	(	Cert *	cert,
		const char *	file
	)

This function sets the alternate names for a certificate to the alternate names in the provided pem file. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the alt names for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the alt names
file	path of the file containing the pem formatted certificate

Example

Cert myCert;
// initialize myCert
if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
    // error setting alt names
}

See also

wc_InitCert

wc_SetIssuer

wc_SetAltNamesBuffer()

int wc_SetAltNamesBuffer	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the alternate names for a certificate from the alternate names in the provided der buffer. This is useful in the case that one wishes to secure multiple domains with the same certificate. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the alternate names for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the alternate names
der	pointer to the buffer containing the der formatted certificate from which to grab the alternate names
derSz	size of the buffer containing the der formatted certificate from which to grab the alternate names

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetAltNamesBuffer(&myCert, der, FOURK_BUF) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetAltNames

wc_SetAuthKeyId()

int wc_SetAuthKeyId	(	Cert *	cert,
		const char *	file
	)

Set AKID from certificate file in PEM format.

Returns

0 Success

BAD_FUNC_ARG Error if cert or file is null.

MEMORY_E Error if problem allocating memory.

Parameters

cert	Cert struct you want to set the AKID of.
file	Buffer containing PEM cert file.

Example

char* file_name = "/path/to/file";
cert some_cert;
wc_InitCert(&some_cert);
 
if(wc_SetAuthKeyId(&some_cert, file_name) != 0)
{
    // Handle Error
}

See also

wc_SetAuthKeyIdFromPublicKey

wc_SetAuthKeyIdFromCert

wc_SetAuthKeyIdFromCert()

int wc_SetAuthKeyIdFromCert	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

Set AKID from from DER encoded certificate.

Returns

0 Success

BAD_FUNC_ARG Error if any argument is null or derSz is less than 0.

MEMORY_E Error if problem allocating memory.

ASN_NO_SKID No subject key ID found.

Parameters

cert	The Cert struct to write to.
der	The DER encoded certificate buffer.
derSz	Size of der in bytes.

Example

Cert some_cert;
byte some_der[] = { // Initialize a DER buffer };
wc_InitCert(&some_cert);
if(wc_SetAuthKeyIdFromCert(&some_cert, some_der, sizeof(some_der) != 0)
{
    // Handle error
}

See also

wc_SetAuthKeyIdFromPublicKey

wc_SetAuthKeyId

wc_SetAuthKeyIdFromPublicKey()

int wc_SetAuthKeyIdFromPublicKey	(	Cert *	cert,
		RsaKey *	rsakey,
		ecc_key *	eckey
	)

Set AKID from either an RSA or ECC public key. note: Only set one of rsakey or eckey, not both.

Returns

0 Success

BAD_FUNC_ARG Either cert is null or both rsakey and eckey are null.

MEMORY_E Error allocating memory.

PUBLIC_KEY_E Error writing to the key.

Parameters

cert	Pointer to the certificate to set the SKID.
rsakey	Pointer to the RsaKey struct to read from.
eckey	Pointer to the ecc_key to read from.

Example

Cert myCert;
RsaKey keypub;
 
wc_InitRsaKey(&keypub, 0);
 
if (wc_SetAuthKeyIdFromPublicKey(&myCert, &keypub, NULL) != 0)
{
    // Handle error
}

See also

wc_SetSubjectKeyId

wc_SetAuthKeyId

wc_SetAuthKeyIdFromCert

wc_SetCert_Free()

void wc_SetCert_Free

(

Cert *

cert

)

This function cleans up memory and resources used by the certificate structure's decoded cert cache. When WOLFSSL_CERT_GEN_CACHE is defined the decoded cert structure is cached in the certificate structure. This allows subsequent calls to certificate set functions to avoid parsing the decoded cert on each call.

Returns

0 on success.

BAD_FUNC_ARG Returned if invalid pointer is passed in as argument.

Parameters

cert	pointer to an uninitialized certificate information structure.

Example

Cert cert; // Initialized certificate structure
 
wc_SetCert_Free(&cert);

See also

wc_SetAuthKeyIdFromCert

wc_SetIssuerBuffer

wc_SetSubjectBuffer

wc_SetSubjectRaw

wc_SetIssuerRaw

wc_SetAltNamesBuffer

wc_SetDatesBuffer

wc_SetCustomExtension()

int wc_SetCustomExtension	(	Cert *	cert,
		int	critical,
		const char *	oid,
		const byte *	der,
		word32	derSz
	)

This function injects a custom extension in to an X.509 certificate. note: The content at the address pointed to by any of the parameters that are pointers must not be modified until the certificate is generated and you have the der output. This function does NOT copy the contents to another buffer.

Returns

0 Returned on success.

Other negative values on failure.

Parameters

cert	Pointer to an initialized DecodedCert object.
critical	If 0, the extension will not be marked critical, otherwise it will be marked critical.
oid	Dot separated oid as a string. For example "1.2.840.10045.3.1.7"
der	The der encoding of the content of the extension.
derSz	The size in bytes of the der encoding.

Example

int ret = 0;
Cert newCert;
wc_InitCert(&newCert);
 
// Code to setup subject, public key, issuer, and other things goes here.
 
ret = wc_SetCustomExtension(&newCert, 1, "1.2.3.4.5",
          (const byte *)"This is a critical extension", 28);
if (ret < 0) {
    // Failed to set the extension.
}
 
ret = wc_SetCustomExtension(&newCert, 0, "1.2.3.4.6",
          (const byte *)"This is NOT a critical extension", 32)
if (ret < 0) {
    // Failed to set the extension.
}
 
// Code to sign the certificate and then write it out goes here.

See also

wc_InitCert

wc_SetUnknownExtCallback

wc_SetDatesBuffer()

int wc_SetDatesBuffer	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the dates for a certificate from the date range in the provided der buffer. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the dates for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the dates
der	pointer to the buffer containing the der formatted certificate from which to grab the date range
derSz	size of the buffer containing the der formatted certificate from which to grab the date range

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetDatesBuffer(&myCert, der, FOURK_BUF) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetIssuer()

int wc_SetIssuer	(	Cert *	cert,
		const char *	issuerFile
	)

This function sets the issuer for a certificate to the issuer in the provided pem issuerFile. It also changes the certificate’s self-signed attribute to false. The issuer specified in issuerFile is verified prior to setting the cert issuer. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the issuer for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the issuer
issuerFile	path of the file containing the pem formatted certificate

Example

Cert myCert;
// initialize myCert
if(wc_SetIssuer(&myCert, ”./path/to/ca-cert.pem”) != 0) {
    // error setting issuer
}

See also

wc_InitCert

wc_SetSubject

wc_SetIssuerBuffer

wc_SetIssuerBuffer()

int wc_SetIssuerBuffer	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the issuer for a certificate from the issuer in the provided der buffer. It also changes the certificate’s self-signed attribute to false. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the issuer for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the issuer
der	pointer to the buffer containing the der formatted certificate from which to grab the issuer
derSz	size of the buffer containing the der formatted certificate from which to grab the issuer

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetIssuerBuffer(&myCert, der, FOURK_BUF) != 0) {
    // error setting issuer
}

See also

wc_InitCert

wc_SetIssuer

wc_SetIssuerRaw()

int wc_SetIssuerRaw	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the raw issuer for a certificate from the issuer in the provided der buffer. This method is used to set the raw issuer field prior to signing.

Returns

0 Returned on successfully setting the issuer for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the raw issuer
der	pointer to the buffer containing the der formatted certificate from which to grab the subject
derSz	size of the buffer containing the der formatted certificate from which to grab the subject

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetIssuerRaw(&myCert, der, FOURK_BUF) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetIssuer

wc_SetSubject()

int wc_SetSubject	(	Cert *	cert,
		const char *	subjectFile
	)

This function sets the subject for a certificate to the subject in the provided pem subjectFile. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the issuer for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the issuer
subjectFile	path of the file containing the pem formatted certificate

Example

Cert myCert;
// initialize myCert
if(wc_SetSubject(&myCert, ”./path/to/ca-cert.pem”) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetIssuer

wc_SetSubjectBuffer()

int wc_SetSubjectBuffer	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the subject for a certificate from the subject in the provided der buffer. This method is used to set fields prior to signing.

Returns

0 Returned on successfully setting the subject for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the subject
der	pointer to the buffer containing the der formatted certificate from which to grab the subject
derSz	size of the buffer containing the der formatted certificate from which to grab the subject

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetSubjectBuffer(&myCert, der, FOURK_BUF) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetSubject

wc_SetSubjectKeyId()

int wc_SetSubjectKeyId	(	Cert *	cert,
		const char *	file
	)

Set SKID from public key file in PEM format. Both arguments are required.

Returns

0 Success

BAD_FUNC_ARG Returns if cert or file is null.

MEMORY_E Returns if there is a problem allocating memory for key.

PUBLIC_KEY_E Returns if there is an error decoding the public key.

Parameters

cert	Cert structure to set the SKID of.
file	Contains the PEM encoded file.

Example

const char* file_name = "path/to/file";
Cert some_cert;
wc_InitCert(&some_cert);
 
if(wc_SetSubjectKeyId(&some_cert, file_name) != 0)
{
    // Handle Error
}

See also

wc_SetSubjectKeyIdFromPublicKey

wc_SetSubjectKeyIdFromPublicKey()

int wc_SetSubjectKeyIdFromPublicKey	(	Cert *	cert,
		RsaKey *	rsakey,
		ecc_key *	eckey
	)

Set SKID from RSA or ECC public key.

Returns

0 Success

BAD_FUNC_ARG Returned if cert or rsakey and eckey are null.

MEMORY_E Returned if there is an error allocating memory.

PUBLIC_KEY_E Returned if there is an error getting the public key.

Parameters

cert	Pointer to a Cert structure to be used.
rsakey	Pointer to an RsaKey structure
eckey	Pointer to an ecc_key structure

Example

Cert some_cert;
RsaKey some_key;
wc_InitCert(&some_cert);
wc_InitRsaKey(&some_key);
 
if(wc_SetSubjectKeyIdFromPublicKey(&some_cert,&some_key, NULL) != 0)
{
    // Handle Error
}

See also

wc_SetSubjectKeyId

wc_SetSubjectRaw()

int wc_SetSubjectRaw	(	Cert *	cert,
		const byte *	der,
		int	derSz
	)

This function sets the raw subject for a certificate from the subject in the provided der buffer. This method is used to set the raw subject field prior to signing.

Returns

0 Returned on successfully setting the subject for the certificate

MEMORY_E Returned if there is an error allocating memory with XMALLOC

ASN_PARSE_E Returned if there is an error parsing the cert header file

ASN_OBJECT_ID_E Returned if there is an error parsing the encryption type from the cert

ASN_EXPECT_0_E Returned if there is a formatting error in the encryption specification of the cert file

ASN_BEFORE_DATE_E Returned if the date is before the certificate start date

ASN_AFTER_DATE_E Returned if the date is after the certificate expiration date

ASN_BITSTR_E Returned if there is an error parsing a bit string from the certificate

ECC_CURVE_OID_E Returned if there is an error parsing the ECC key from the certificate

ASN_UNKNOWN_OID_E Returned if the certificate is using an unknown key object id

ASN_VERSION_E Returned if the ALLOW_V1_EXTENSIONS option is not defined and the certificate is a V1 or V2 certificate

BAD_FUNC_ARG Returned if there is an error processing the certificate extension

ASN_CRIT_EXT_E Returned if an unfamiliar critical extension is encountered in processing the certificate

ASN_SIG_OID_E Returned if the signature encryption type is not the same as the encryption type of the certificate in the provided file

ASN_SIG_CONFIRM_E Returned if confirming the certification signature fails

ASN_NAME_INVALID_E Returned if the certificate’s name is not permitted by the CA name constraints

ASN_NO_SIGNER_E Returned if there is no CA signer to verify the certificate’s authenticity

Parameters

cert	pointer to the cert for which to set the raw subject
der	pointer to the buffer containing the der formatted certificate from which to grab the subject
derSz	size of the buffer containing the der formatted certificate from which to grab the subject

Example

Cert myCert;
// initialize myCert
byte* der;
der = (byte*)malloc(FOURK_BUF);
// initialize der
if(wc_SetSubjectRaw(&myCert, der, FOURK_BUF) != 0) {
    // error setting subject
}

See also

wc_InitCert

wc_SetSubject

wc_SetTimeCb()

int wc_SetTimeCb

(

wc_time_cb

f

)

This function registers a time callback that will be used anytime wolfSSL needs to get the current time. The prototype of the callback should be the same as the "time" function from the C standard library.

Returns

0 Returned on success.

Parameters

f	function to register as the time callback.

Example

int ret = 0;
// Time callback prototype
time_t my_time_cb(time_t* t);
// Register it
ret = wc_SetTimeCb(my_time_cb);
if (ret != 0) {
    // failed to set time callback
}
time_t my_time_cb(time_t* t)
{
    // custom time function
}

See also

wc_Time

wc_SetUnknownExtCallback()

int wc_SetUnknownExtCallback	(	DecodedCert *	cert,
		wc_UnknownExtCallback	cb
	)

This function registers a callback that will be used anytime wolfSSL encounters an unknown X.509 extension in a certificate while parsing a certificate. The prototype of the callback should be:

Returns

0 Returned on success.

Other negative values on failure.

Parameters

cert	the DecodedCert struct that is to be associated with this callback.
cb	function to register as the time callback.

Example

int ret = 0;
// Unknown extension callback prototype
int myUnknownExtCallback(const word16* oid, word32 oidSz, int crit,
                         const unsigned char* der, word32 derSz);
 
// Register it
ret = wc_SetUnknownExtCallback(cert, myUnknownExtCallback);
if (ret != 0) {
    // failed to set the callback
}
 
// oid: Array of integers that are the dot separated values in an oid.
// oidSz: Number of values in oid.
// crit: Whether the extension was mark critical.
// der: The der encoding of the content of the extension.
// derSz: The size in bytes of the der encoding.
int myCustomExtCallback(const word16* oid, word32 oidSz, int crit,
                        const unsigned char* der, word32 derSz) {
 
    // Logic to parse extension goes here.
 
    // NOTE: by returning zero, we are accepting this extension and
    // informing wolfSSL that it is acceptable. If you find an extension
    // that you do not find acceptable, you should return an error. The
    // standard behavior upon encountering an unknown extension with the
    // critical flag set is to return ASN_CRIT_EXT_E. For the sake of
    // brevity, this example is always accepting every extension; you
    // should use different logic.
    return 0;
}

See also

ParseCert

wc_SetCustomExtension

wc_SignCert()

int wc_SignCert	(	int	requestSz,
		int	sigType,
		byte *	derBuffer,
		word32	derSz,
		RsaKey *	rsaKey,
		ecc_key *	eccKey,
		WC_RNG *	rng
	)

This function signs buffer and adds the signature to the end of buffer. It takes in a signature type. Must be called after wc_MakeCert() or wc_MakeCertReq() if creating a CA signed cert.

Returns

Success On successfully signing the certificate, returns the new size of the cert (including signature).

MEMORY_E Returned if there is an error allocating memory with XMALLOC

BUFFER_E Returned if the provided buffer is too small to store the generated certificate

Other Additional error messages may be returned if the cert generation is not successful.

Parameters

requestSz	the size of the certificate body we’re requesting to have signed
sType	Type of signature to create. Valid options are: CTC_MD5wRSA, CTC_SHAwRSA, CTC_SHAwECDSA, CTC_SHA256wECDSA, and CTC_SHA256wRSA
buffer	pointer to the buffer containing the certificate to be signed. On success: will hold the newly signed certificate
buffSz	the (total) size of the buffer in which to store the newly signed certificate
rsaKey	pointer to an RsaKey structure containing the rsa key to used to sign the certificate
eccKey	pointer to an EccKey structure containing the ecc key to used to sign the certificate
rng	pointer to the random number generator used to sign the certificate

Example

Cert myCert;
byte* derCert = (byte*)malloc(FOURK_BUF);
// initialize myCert, derCert
RsaKey key;
// initialize key;
WC_RNG rng;
// initialize rng
 
word32 certSz;
certSz = wc_SignCert(myCert.bodySz, myCert.sigType,derCert,FOURK_BUF,
&key, NULL,
&rng);

See also

wc_InitCert

wc_MakeCert

wc_Time()

time_t wc_Time

(

time_t *

t

)

This function gets the current time. By default, it uses the XTIME macro, which varies between platforms. The user can use a function of their choosing instead via the wc_SetTimeCb function.

Returns

Time Current time returned on success.

Parameters

t	Optional time_t pointer to populate with current time.

Example

time_t currentTime = 0;
currentTime = wc_Time(NULL);
wc_Time(&currentTime);

See also

wc_SetTimeCb