sys_add_key  [security/keys/keyctl.c]


Creates a new key of given type, description and payload and add it to the nominated keyring.

If a key of the same type and description as that proposed already exists in the keyring, this will try to update it with the given payload, or it will return error -EEXIST if that function is not supported by the key type. The process must also have permission to write to the key to be able to update it. The new key will have all user permissions granted and no group or third party permissions. Otherwise, this will attempt to create a new key of the specified type and description, and to instantiate it with the supplied payload and attach it to the keyring. In this case, an error will be generated if the process does not have permission to write to the keyring.
The payload is optional, and the pointer can be 0 if not required by the type.
A new keyring can be generated by setting type "keyring", the keyring name as the description (or 0) and setting the payload to 0.
User defined keys can be created by specifying type "user". It is recommended that a user defined key's description by prefixed with a type ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting ticket.
Any other type must have been registered with the kernel in advance by a kernel service such as a filesystem.

Arguments

eax 286
ebx Pointer to a null-terminated string that specifies the type.
ecx Pointer to a null-terminated string that specifies the description.
edx Pointer to a null-terminated string that specifies the payload.
esi Size of the payload. Should not exceed 32767 bytes.
edi A positive non-zero 32-bit integer that specifies unique serial number for the key. It may be one of the predefined values:
KEY_SPEC_THREAD_KEYRING       - Specifies the caller's thread-specific keyring.
KEY_SPEC_PROCESS_KEYRING      - Specifies the caller's process-specific keyring.
KEY_SPEC_SESSION_KEYRING      - Specifies the caller's session-specific keyring.
KEY_SPEC_USER_KEYRING         - Specifies the caller's UID-specific keyring.
KEY_SPEC_USER_SESSION_KEYRING - Specifies the caller's UID-session keyring.
KEY_SPEC_GROUP_KEYRING        - GID-specific keyring
KEY_SPEC_REQKEY_AUTH_KEY      - assumed sys_request_key authorisation key

Return values

If the system call succeeds the return value is the new key's ID.
If the system call fails the return value is one of the following errno values:

-ENOKEY The keyring doesn't exist.
-EKEYEXPIRED The keyring has expired.
-EKEYREVOKED The keyring has been revoked.
-EINVAL The payload data was invalid.
-ENOMEM Insufficient memory to create a key.
-EDQUOT The key quota for this user would be exceeded by creating this key or linking it to the keyring.
-EACCES The keyring wasn't available for modification by the user.

Remarks

The keyring must be writable.

Compatibility

Available since 2.6.10