(mozilla-projects-nss-reference-fc-initpin)=

# FC_InitPIN

## [Name](#name)

:::{container}
`FC_InitPIN()` - Initialize the user's PIN.
:::

## [Syntax](#syntax)

:::{container}

```{code}
CK_RV FC_InitPIN(
  CK_SESSION_HANDLE hSession,
  CK_CHAR_PTR pPin,
  CK_ULONG ulPinLen
);
```

:::

## [Parameters](#parameters)

:::{container}
`FC_InitPIN()` takes three parameters:

`hSession`

: [Input] Session handle.

`pPin`

: [Input] Pointer to the PIN being set.

`ulPinLen`

: [Input] Length of the PIN.
:::

## [Description](#description)

:::{container}
`FC_InitPIN()` initializes the normal user's PIN.

`FC_InitPIN()` must be called when the PKCS #11 Security Officer (SO) is logged into the token
and the session is read/write, that is, the session must be in the "R/W SO Functions" state
(`CKS_RW_SO_FUNCTIONS`). The role of the PKCS #11 SO is to initialize a token and to initialize
the normal user's PIN. In the NSS cryptographic module, one uses the empty string password ("")
to log in as the PKCS #11 SO. The module only allows the PKCS #11 SO to log in if the normal
user's PIN has not yet been set or has been reset.
:::

## [Return value](#return_value)

:::{container}
`FC_InitPIN()` returns the following return codes.

- `CKR_OK`: normal user's PIN initialization succeeded.
- `CKR_SESSION_HANDLE_INVALID`: the session handle is invalid.
- `CKR_USER_NOT_LOGGED_IN`: the session is not in the "R/W SO Functions" state.
- `CKR_PIN_INVALID`: the PIN has an invalid UTF-8 character.
- `CKR_PIN_LEN_RANGE`: the PIN is too short, too long, or too weak (doesn't have enough
  character types).
- `CKR_DEVICE_ERROR`: normal user's PIN is already initialized.
:::

## [See also](#see_also)

:::{container}

- [NSC_InitPIN](/en-US/NSC_InitPIN), {ref}`mozilla_projects_nss_reference_fc_setpin`
:::