---
name: "RAND_DRBG_new"
section: "3ssl"
platform: "linux"
package: "libssl-doc"
version: "1.1.1w-0+deb11u1"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/RAND_DRBG_new"
---

# RAND\_DRBG\_new(3ssl)

initialize and cleanup a RAND\_DRBG instance

## NAME

RAND\_DRBG\_new, RAND\_DRBG\_secure\_new, RAND\_DRBG\_set, RAND\_DRBG\_set\_defaults, RAND\_DRBG\_instantiate, RAND\_DRBG\_uninstantiate, RAND\_DRBG\_free - initialize and cleanup a RAND\_DRBG instance

## SYNOPSIS

```
 #include <openssl/rand_drbg.h>
 RAND_DRBG *RAND_DRBG_new(int type,
                          unsigned int flags,
                          RAND_DRBG *parent);
 RAND_DRBG *RAND_DRBG_secure_new(int type,
                                 unsigned int flags,
                                 RAND_DRBG *parent);
 int RAND_DRBG_set(RAND_DRBG *drbg,
                   int type, unsigned int flags);
 int RAND_DRBG_set_defaults(int type, unsigned int flags);
 int RAND_DRBG_instantiate(RAND_DRBG *drbg,
                           const unsigned char *pers, size_t perslen);
 int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
 void RAND_DRBG_free(RAND_DRBG *drbg);
```

## DESCRIPTION

**RAND\_DRBG\_new()** and **RAND\_DRBG\_secure\_new()** create a new DRBG instance of the given **type**, allocated from the heap resp. the secure heap (using **OPENSSL\_zalloc()** resp. **OPENSSL\_secure\_zalloc()**).

**RAND\_DRBG\_set()** initializes the **drbg** with the given **type** and **flags**.

**RAND\_DRBG\_set\_defaults()** sets the default **type** and **flags** for new DRBG instances.

Currently, all DRBG types are based on AES-CTR, so **type** can be one of the following values: NID\_aes\_128\_ctr, NID\_aes\_192\_ctr, NID\_aes\_256\_ctr. Before the DRBG can be used to generate random bits, it is necessary to set its type and to instantiate it.

The optional **flags** argument specifies a set of bit flags which can be joined using the \| operator. Currently, the only flag is RAND\_DRBG\_FLAG\_CTR\_NO\_DF, which disables the use of the derivation function ctr\_df. For an explanation, see \[NIST SP 800-90A Rev. 1\].

If a **parent** instance is specified then this will be used instead of the default entropy source for reseeding the **drbg**. It is said that the **drbg** is *chained* to its **parent**. For more information, see the NOTES section.

**RAND\_DRBG\_instantiate()** seeds the **drbg** instance using random input from trusted entropy sources. Optionally, a personalization string **pers** of length **perslen** can be specified. To omit the personalization string, set **pers**=NULL and **perslen**=0;

**RAND\_DRBG\_uninstantiate()** clears the internal state of the **drbg** and puts it back in the uninstantiated state.

## RETURN VALUES

**RAND\_DRBG\_new()** and **RAND\_DRBG\_secure\_new()** return a pointer to a DRBG instance allocated on the heap, resp. secure heap.

**RAND\_DRBG\_set()**, **RAND\_DRBG\_instantiate()**, and **RAND\_DRBG\_uninstantiate()** return 1 on success, and 0 on failure.

**RAND\_DRBG\_free()** does not return a value.

## NOTES

The DRBG design supports *chaining*, which means that a DRBG instance can use another **parent** DRBG instance instead of the default entropy source to obtain fresh random input for reseeding, provided that **parent** DRBG instance was properly instantiated, either from a trusted entropy source, or from yet another parent DRBG instance. For a detailed description of the reseeding process, see **RAND\_DRBG**(7).

The default DRBG type and flags are applied only during creation of a DRBG instance. To ensure that they are applied to the global and thread-local DRBG instances (\<master\>, resp. \<public\> and \<private\>), it is necessary to call **RAND\_DRBG\_set\_defaults()** before creating any thread and before calling any cryptographic routines that obtain random data directly or indirectly.

## SEE ALSO

**OPENSSL\_zalloc**(3), **OPENSSL\_secure\_zalloc**(3), **RAND\_DRBG\_generate**(3), **RAND\_DRBG**(7)

## HISTORY

The RAND\_DRBG functions were added in OpenSSL 1.1.1.

## COPYRIGHT

Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use this file except in compliance with the License.  You can obtain a copy in the file LICENSE in the source distribution or at \<https://www.openssl.org/source/license.html\>.