add_key — add a key to the kernel's key management facility
||const char *type,|
|const char *description,|
|const void *payload,|
add_key() asks the kernel to
create or update a key of the given
description, instantiate it
plen, and to
attach it to the nominated
keyring and to return its
The key type may reject the data if it's in the wrong format or in some other way invalid.
If the destination
keyring already contains a key
that matches the specified
description, then, if the key
type supports it, that key will be updated rather than a new
key being created; if not, a new key will be created and it
will displace the link to the extant key from the
keyring serial number may be
that of a valid keyring to which the caller has write
permission, or it may be a special keyring ID:
This specifies the caller's thread-specific keyring.
This specifies the caller's process-specific keyring.
This specifies the caller's session-specific keyring.
This specifies the caller's UID-specific keyring.
This specifies the caller's UID-session keyring.
There are a number of key types available in the core key management code, and these can be specified to this function:
Keys of the user-defined key type may contain a blob
of arbitrary data, and the
description may be any
valid string, though it is preferred that the
description be prefixed with a string representing the
service to which the key is of interest and a colon
(for instance “
Keyrings are special key types that may contain
links to sequences of other keys of any type. If this
interface is used to create a keyring, then a NULL
be specified, and
plen should be zero.
the serial number of the key it created or updated. On error,
the value −1 will be returned and errno will have been
set to an appropriate error.
The keyring doesn't exist.
The keyring has expired.
The keyring has been revoked.
The payload data was invalid.
Insufficient memory to create a key.
The key quota for this user would be exceeded by creating this key or linking it to the keyring.
The keyring wasn't available for modification by the user.
Although this is a Linux system call, it is not present in
libc but can be
found rather in
libkeyutils. When linking,
−lkeyutils should be
specified to the linker.
This page is part of release 4.07 of the Linux
man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
Written by David Howells (dhowellsredhat.com)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.